# marcusng/flutter_riverpod_quiz architecture

> Architecture diagram of the GitHub repository marcusng/flutter_riverpod_quiz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcusng/flutter_riverpod_quiz
- Repository: https://github.com/marcusng/flutter_riverpod_quiz

## Overview

##### Project Type & Purpose
- It’s a cross-platform mobile application (Flutter) that presents quiz questions to users.
- It uses Riverpod for state management and follows a repository-based data layer.

##### File Structure
- Top-level mobile platforms:
– android/… (Gradle files, native Android boilerplate)
– ios/… (Xcode project, Swift AppDelegate, asset catalogs)
- lib/… (Dart code) broken into:
– controllers/quiz (QuizController, QuizState)
– enums (difficulty levels)
– models (Question, Failure)
– repositories/quiz (abstract BaseQuizRepository, concrete QuizRepository)
– main.dart (app entry point, provider scope)
- test/widget_test.dart (UI smoke test)
- pubspec.yaml (dependencies: flutter_riverpod, http, etc.)

##### Key README Insights
- No backend code in repo – likely calls an external trivia API (via QuizRepository).
- State managed with Riverpod providers in controllers.

##### Main Components
a. Presentation Layer (UI Widgets)
– Screens: Quiz screen, loading/error views
– Riverpod ConsumerWidgets or WidgetRefs
b. State Management Layer
– QuizController (StateNotifier/StateNotifierProvider)
– QuizState (holds loading, questions, error)
c. Domain/Data Layer
– QuizRepository interface (BaseQuizRepository)
– QuizRepository implementation (makes HTTP calls)
– Models: QuestionModel, FailureModel
– Enums: Difficulty
d. External Service
– Remote Trivia API (REST endpoint)
e. Platform Runtime
– Flutter Engine on Android & iOS

##### Relationships & Data Flow
1. UI Widget dispatches an event (e.g., “startQuiz”) via Riverpod provider.
2. QuizController receives the event, sets state to loading.
3. Controller invokes QuizRepository.fetchQuestions(difficulty).
4. Repository issues HTTP request to external Trivia API.
5. API returns JSON → parsed into List<QuestionModel> or Failure.
6. Controller updates QuizState with success or failure.
7. UI rebuilds based on new state.

##### Architectural Patterns & Principles
- Layered/Clean Architecture:
– UI → State (Riverpod) → Repository → External API
- Separation of concerns: UI logic vs. state logic vs. data logic
- Dependency inversion via abstract BaseQuizRepository

##### Technologies & Frameworks
- Flutter (Dart) – UI toolkit
- flutter_riverpod – state management
- http (or similar) – network calls
- StateNotifier/StateNotifierProvider – for controllers
- JSON serialization (manual or built_value/freezed)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        UI["UI Widgets\n(ConsumerWidgets)"]:::ui
    end

    %% State Management Layer
    subgraph "State Management Layer"
        direction TB
        QC["QuizController\n(StateNotifier)"]:::ui
        QS["QuizState"]:::ui
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DFE["Difficulty\n(enum)"]:::ui
        QM["QuestionModel"]:::ui
        FM["FailureModel"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        BQR["BaseQuizRepository\n(abstract)"]:::data
        QR["QuizRepository\n(concrete)"]:::data
    end

    %% External Service
    EX["External Trivia API"]:::external

    %% Platform Runtimes
    subgraph "Platform Runtimes"
        direction TB
        Android["Android\n(MainActivity.kt)"]:::platform
        iOS["iOS\n(AppDelegate.swift)"]:::platform
    end

    %% Relationships
    UI -->|"read/writes state"| QC
    QC -->|"holds state"| QS
    QC -->|"calls fetchQuestions()"| BQR
    BQR -->|"implemented by"| QR
    QR -->|"HTTP request"| EX
    EX -->|"JSON response"| QR
    QR -->|"returns models/failure"| QC
    QC -->|"updates"| QS
    QS -->|"notifies"| UI

    Android --- UI
    iOS --- UI

    %% Click Events
    click UI "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/main.dart"
    click QC "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/controllers/quiz/quiz_controller.dart"
    click QS "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/controllers/quiz/quiz_state.dart"
    click DFE "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/enums/difficulty.dart"
    click QM "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/models/question_model.dart"
    click FM "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/models/failure_model.dart"
    click BQR "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/repositories/quiz/base_quiz_repository.dart"
    click QR "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/lib/repositories/quiz/quiz_repository.dart"
    click Android "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/android/app/src/main/kotlin/com/example/flutter_riverpod_quiz/MainActivity.kt"
    click iOS "https://github.com/marcusng/flutter_riverpod_quiz/blob/master/ios/Runner/AppDelegate.swift"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef platform fill:#D3D3D3,stroke:#333,stroke-width:1px
```
