🌟 Official Versions

Access Quiz App on your favorite platform:

• 🌐 Web: vicajilau.github.io/quiz_app Enjoy the full experience from any browser.

• 📱 Android: Google Play Store Install the app on your Android device and learn anywhere.

• 🪟 Windows: Microsoft Store Download and install on Windows 10/11 with automatic updates.

• 🐧 Linux: Snapcraft Download and install easily on any Linux distribution compatible with Snap.

Note: MacOS and iOS versions are under development and will be added soon.

A cross-platform Flutter application that provides an interactive and engaging quiz experience with customizable questions, real-time scoring, and beautiful animations.

The app provides an intuitive interface for taking quizzes with smooth animations, real-time feedback, and comprehensive score tracking, as shown above.

• Cross-platform compatibility: Built with Flutter to run seamlessly on iOS, Android, web, and desktop
• Multiple question types: Support for multiple choice, single choice, true/false, and essay questions
• Real-time scoring: Instant feedback and score calculation during quiz sessions
• Beautiful UI/UX: Modern Material Design with smooth animations and responsive layouts
• Quiz customization: Create and customize your own quizzes with flexible question configurations
• Progress tracking: Track performance across multiple quiz sessions with detailed analytics
• Offline support: Take quizzes without internet connection
• ⏱️ Exam Timer: Configurable time limits with countdown display and automatic submission when time expires
• 🎲 Question Randomization: Randomize question order and answer options for varied quiz experiences

• Interactive Participant Management: Add, edit, and remove participants with real-time validation and duplicate detection
• Animated Winner Selection: Smooth animations and visual effects during the selection process
• Multiple Winner Support: Select multiple winners with automatic position tracking (1st, 2nd, 3rd place, etc.)
• Custom Logo Integration: Personalize raffle events with company or event logos displayed in the app header
• Winners History: Elegant display of all selected winners with timestamps and position rankings
• Results Sharing: Export and share raffle results via clipboard with formatted text output
• Comprehensive Localization: Full multi-language support for all raffle features across 13 languages
• Clean Architecture: BLoC state management with reactive UI updates and efficient participant handling

• Multi-AI Service Support: Integrated support for Google Gemini and OpenAI GPT
• Intelligent Question Creation: Generate quiz questions from any text content using AI
• Flexible Question Types: AI can create multiple choice, single choice, true/false, essay, or random question types
• Multi-language Support: Generate questions in 13 languages including English, Spanish, French, German, Italian, Portuguese, Catalan, Basque, Galician, Hindi, Chinese, Arabic, and Japanese
• Smart Content Analysis: AI analyzes your content and creates relevant, educational questions
• Service-Specific Optimization: Dynamic limits and validation based on selected AI service
• Configurable Limits: Intelligent word and character limits that adapt to each AI service's capabilities
• 🤖 AI Study Assistant: Interactive AI tutor that can discuss questions, explain concepts, and provide context-aware help during quiz sessions

• Full Localization: Complete support for 13 languages including English, Spanish, French, German, Italian, Portuguese, Catalan, Basque, Galician, Hindi, Chinese, Arabic, and Japanese
• Dynamic Language Switching: Seamless language changes throughout the app
• Localized AI Content: AI-generated questions respect the selected language preference

Quiz App follows Clean Architecture principles with clear separation of concerns across multiple layers. The app is designed for maintainability, testability, and extensibility.

• Presentation Layer: UI components, screens, dialogs, and state management
• Domain Layer: Business logic, use cases, and domain models
• Data Layer: Services, repositories, and external API integrations

• Multi-platform Support: Flutter-based cross-platform compatibility
• AI Integration: Pluggable AI services with dynamic configuration
• Internationalization: ARB-based localization system
• Clean Architecture: SOLID principles with dependency injection
• Comprehensive Testing: Unit, widget, and integration test coverage

For detailed technical documentation including data models, project structure, architectural patterns, and data flow diagrams, see: Application Structure Documentation

The app features advanced AI integration for automatic question generation:

// Supported AI services with dynamic limits
enum AIServiceType {
  gemini,   // Google Gemini
  openai,   // OpenAI GPT models
}

class AiQuestionGenerationConfig {
  final int? questionCount;
  final AiQuestionType questionType;
  final String language;
  final String content;
  final AIService? preferredService;
}

enum AiQuestionType {
  multipleChoice,  // Multiple choice with several options
  singleChoice,    // Single correct choice
  trueFalse,       // True/false questions
  essay,           // Open-ended essay questions
  random,          // Mix of different types
}

For detailed information about AI service limits and configuration, see: AI Limits System Documentation

1. Launch the app and navigate to the quiz editor
2. Click the AI generation button (⚡ icon)
3. Configure your preferred AI service:
   • Choose between OpenAI GPT or Google Gemini
   • Enter your API key when prompted
   • The app will validate your configuration

1. Prepare your content: Write or paste the text you want to generate questions from
2. Configure generation settings:
   • Question Count: How many questions to generate (1-50)
   • Question Type: Multiple choice, single choice, true/false, essay, or random mix
   • Language: Select from 13 supported languages
   • AI Service: Choose your preferred AI service
3. Monitor content limits: The app shows real-time word count and service-specific limits
4. Generate: Click generate and the AI will create relevant questions from your content

1. Launch the app and navigate to the main menu
2. Select "Raffle" from the navigation options
3. Start creating your raffle by adding participants

1. Add Participants:

   • Enter participant names one by one
   • Paste a list of names (one per line) for bulk import
   • Edit or remove participants as needed
   • Real-time validation prevents duplicates

2. Customize Your Event (Optional):

   • Add a custom logo URL for your company or event
   • The logo will appear in the app header for brand consistency
   • Logo preview shows before applying changes

3. Run the Raffle:

   • Click "Select Winner" to start the animated selection
   • Watch the exciting animation as a winner is chosen
   • Select multiple winners for 1st, 2nd, 3rd place and beyond

• View Winners: Navigate to the Winners screen to see all selected participants
• Share Results: Export results to clipboard with formatted text including positions and timestamps
• Start New Raffle: Reset and begin a fresh raffle session anytime

1. Access Settings: Go to Quiz Settings from the main menu
2. Enable Timer: Toggle "Enable time limit" switch
3. Set Duration: Enter desired time limit in minutes (1-999)
4. Start Quiz: Timer automatically starts when quiz begins
5. Monitor Progress: Watch the countdown in the top-right corner during quiz

1. During Quiz: Click the "AI" button (🤖) next to any question
2. Automatic Context: AI automatically loads:
   • Question text and all answer options
   • Any existing explanations
   • Question type and context
3. Ask Questions: Type your question about the topic, concept, or answer choices
4. Get Explanations: AI provides detailed, educational responses
5. Continue Learning: Ask follow-up questions for deeper understanding

• Concept Explanation: "Explain the main concept behind this question"
• Answer Analysis: "Why is option B correct and C incorrect?"
• Additional Context: "Can you provide more examples of this topic?"
• Study Tips: "What should I focus on to understand this better?"
• Related Topics: "How does this relate to [other concept]?"

• Flexible Time Limits: Set custom time limits for exams (1-999 minutes)
• Visual Countdown: Real-time countdown timer with color-coded warnings
• Automatic Submission: Quiz automatically submits when time expires
• Timer Control: Enable/disable timer functionality per quiz session
• Progress Indication: Visual progress bar showing remaining time percentage

• Context-Aware Help: AI automatically loads question context and options for informed discussions
• Multi-Service Support: Choose between OpenAI GPT and Google Gemini for different interaction styles
• Intelligent Explanations: Get detailed explanations about question concepts, answer reasoning, and related topics
• Interactive Chat: Ask follow-up questions and engage in educational conversations
• Question Analysis: AI can explain why answers are correct/incorrect and provide additional learning resources
• Language Adaptive: AI responds in the same language as the question content
• Real-Time Assistance: Get help while taking quizzes without interrupting your flow

• Flutter SDK 3.0.0 or higher
• Dart SDK 3.0.0 or higher
• Android Studio / Xcode for mobile development
• A device or emulator for testing

• OpenAI API Key: For GPT-powered question generation
• Google AI API Key: For Gemini-powered question generation
• Internet connection for AI services (quiz taking works offline)

1. Clone this repository

   git clone https://github.com/vicajilau/quiz_app.git
   cd quiz_app

2. Install dependencies

   flutter pub get

3. Run the app

   flutter run

4. Build for production

   • Android: flutter build apk --release
   • iOS: flutter build ios --release
   • Web: flutter build web --release

5. Configure AI Services (Optional)

   To enable AI question generation, you need to configure API keys:

   • OpenAI: Get your API key from OpenAI Platform
   • Google AI: Get your API key from Google AI Studio

   The app will guide you through the configuration process when you first try to use AI features.

• flutter run: Run the app in development mode
• flutter run --release: Run the app in release mode
• flutter test: Run unit and widget tests
• flutter build apk: Build Android APK
• flutter build ios: Build iOS app
• flutter build web: Build web version

1. During active development:

   flutter run --hot-reload

   This enables hot reload for instant code changes.

2. To test changes:

   • Save your changes and see instant updates with hot reload
   • Use r to hot reload, R to hot restart

3. Before committing:

   flutter analyze          # Check for any issues
   flutter test            # Run all tests
   flutter build apk --release  # Verify release build works

4. To create a new version:

   # 1. Update version in pubspec.yaml
   # 2. Run tests to ensure quality
   flutter test
   
   # 3. Build release versions
   flutter build apk --release
   flutter build ios --release
   
   # 4. Test on physical devices

The app includes comprehensive testing to ensure quiz functionality and AI integration:

• Unit tests: Core business logic, quiz mechanics, and AI service integration
• Widget tests: UI components, user interactions, and AI dialog functionality
• Integration tests: End-to-end quiz flow testing including AI question generation
• Performance tests: App responsiveness, memory usage, and AI service performance
• AI Service tests: Validation of AI service limits, content validation, and error handling

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/quiz_logic_test.dart

# Run integration tests
flutter test integration_test/

The app validates:

• Quiz structure:

  • Valid question types and formats
  • Correct answer validation
  • Score calculation accuracy
  • Time tracking functionality

• User interactions:

  • Answer selection and submission
  • Navigation between questions
  • Quiz completion flow
  • Result calculation and display

• AI Integration:

  • Service availability and API key validation
  • Content length and format validation
  • Dynamic limit enforcement
  • Error handling for AI service failures
  • Multi-language content generation

• Data persistence: Progress saving, quiz history, and AI service configuration

The app is designed to easily support new question types, AI services, and features:

// Currently supported question types
enum QuestionType {
  multipleChoice,
  singleChoice,
  trueFalse,
  essay,
}

// Currently supported AI services
enum AIServiceType {
  openai,
  gemini,
}

// Future support planned
enum QuestionType {
  multipleChoice,
  singleChoice,
  trueFalse,
  essay,
  fillInBlank,
  matching,
  dragAndDrop,
  ordering,
}

// Future AI services
enum AIServiceType {
  openai,
  gemini,
  claude,
  cohere,
}

For detailed technical documentation including complete project structure, data models, and architectural patterns, see: Application Structure Documentation

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a branch for your feature:

   git checkout -b feature/new-question-type

3. Make changes and test:

   flutter analyze        # Check for any issues
   flutter test          # Verify tests pass

4. Test the app:

   # Test on different platforms
   flutter run -d android
   flutter run -d ios
   flutter run -d chrome

5. Commit and push:

   git add .
   git commit -m "feat: add drag and drop question type support"
   git push origin feature/new-question-type

6. Create Pull Request

• Commits: Use Conventional Commits

  • feat: for new features (e.g., new question types, UI improvements)
  • fix: for bug fixes
  • docs: for documentation changes
  • refactor: for code refactoring
  • test: for adding or modifying tests

• Code:

  • Follow Flutter/Dart style guidelines
  • Use meaningful variable and function names
  • Add comments for complex logic
  • Ensure responsive design for different screen sizes
  • Update tests when adding new features

To add a new question type:

1. Create the question model (lib/domain/models/)
2. Add question type enum (lib/core/constants/)
3. Implement UI widgets (lib/presentation/widgets/)
4. Add business logic (lib/domain/use_cases/)
5. Update repositories (lib/data/repositories/)
6. Add AI generation support if applicable
7. Add tests for the new functionality

To add a new AI service:

1. Implement AIService interface (lib/data/services/ai/)
2. Add service limits in AILimitsConfig
3. Update AIServiceSelector
4. Add service-specific configuration
5. Add localization strings
6. Add comprehensive tests

For detailed information, see: AI Limits System Documentation

• Main README: This file - comprehensive overview and setup guide
• Application Structure: Detailed technical documentation about app architecture, data models, and project structure
• AI Limits System: Detailed documentation about AI service integration, limits, and configuration

• AI Question Generation: Automatic question creation from text content using multiple AI services
• AI Study Assistant: Interactive tutor for explaining concepts and providing context-aware help during quizzes
• Exam Timer System: Configurable time limits with visual countdown and automatic submission
• Multi-language Support: Full internationalization with 13 language support
• Dynamic Service Limits: Intelligent content validation based on selected AI service capabilities
• Cross-platform Compatibility: Seamless operation across iOS, Android, web, and desktop platforms
• Question Randomization: Flexible ordering and answer shuffling for varied quiz experiences

• Clean Architecture: Separation of concerns with data, domain, and presentation layers
• Dependency Injection: Service locator pattern for maintainable code
• State Management: Provider pattern for reactive UI updates
• Localization: ARB-based internationalization system

If you find a bug or have a suggestion:

1. Check that a similar issue doesn't already exist
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Screenshots if applicable
   • Device information (OS, Flutter version)
   • Expected vs actual behavior
   • For AI-related issues: Include AI service used, content length, and error messages

We welcome suggestions for:

• New AI services integration (Claude, Cohere, etc.)
• Additional question types (fill-in-blank, matching, drag-and-drop)
• Enhanced AI capabilities (difficulty adaptation, topic detection, personalized learning paths)
• Advanced timer features (pause/resume, time extensions, per-question timing)
• Expanded AI assistant (voice interactions, multimedia explanations, study plan generation)
• New languages for localization
• Quiz analytics and performance tracking

This project is under the MIT license.