# omarfettal/smartquiz architecture

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

- Interactive diagram: https://gitdiagram.com/omarfettal/smartquiz
- Repository: https://github.com/omarfettal/smartquiz

## Overview

##### Project type and purpose
- This is a cross-platform (Android, iOS, Web, Linux, macOS, Windows) Flutter quiz application.
- Purpose: allow users to sign up/log in, take quizzes, create quizzes, view results, manage their profile and preferences.

##### File structure
- Top-level platform folders: android/, ios/, linux/, macos/, web/, windows/ – each hosts the native shell and Flutter engine integration.
- lib/: the single Dart codebase
- lib/screens/: presentation layer (all UI pages: login, signup, quiz pages, result page, settings, etc.)
- lib/main.dart: app entrypoint, sets up routing, dependency injection (AuthGate, ThemeProvider)
- test/: widget_test.dart for UI tests
- pubspec.yaml / pubspec.lock: lists dependencies (e.g., flutter, provider, http, firebase_* if used)

##### Key insights from README
- Default Flutter README with no extra architectural details.
- We must infer architecture from code organization: a typical three-layer Flutter app (Presentation → Business Logic → Data/Services).

##### Main components and their interactions
a. Platform Host layers
- Android Shell
- iOS Shell
- Web Host (index.html + web_entrypoint)
- Linux/MacOS/Windows wrappers

b. Flutter Engine & Embedder
- Renders UI, executes Dart VM, manages platform channels

c. Dart Application Layers
1. Presentation Layer (“Screens” UI)
– All widgets in lib/screens/
– Receives user input, navigates via Navigator
2. Business-Logic Layer (“Utils” services)
– auth_service.dart: handles sign-in/sign-up, session state
– themeprovider.dart: manages app theme state
3. Data Layer
– quizData.dart: model classes and repository calls to a backend/DB
– May use HTTP or Firebase SDKs to fetch/store quiz data

d. External Services (if applicable)
- Authentication provider (e.g., Firebase Auth or custom API)
- Quiz storage backend (e.g., RESTful API or Firebase Firestore)

##### Architectural patterns and design principles
- Layered architecture: clear separation of UI, business logic, data access
- Dependency injection via top-level providers (AuthGate, ThemeProvider)
- MVVM/MVC-style separation (Screens act as Views, Utils act as ViewModels/Controllers)
- Cross-platform code reuse: single lib/ folder for all platforms

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Hosts
    subgraph "Platform Hosts" 
        direction TB
        AndroidShell["Android Shell"]:::platform
        iOSShell["iOS Shell"]:::platform
        WebHost["Web Host"]:::platform
        LinuxWrapper["Linux Wrapper"]:::platform
        MacOSWrapper["macOS Wrapper"]:::platform
        WindowsWrapper["Windows Wrapper"]:::platform
    end

    %% Main App Container
    subgraph "SmartQuiz Flutter App"
        direction TB
        Engine["Flutter Engine & Dart VM"]:::engine

        subgraph "Presentation Layer" 
            direction TB
            LoginPage["Login Page"]:::ui
            SignupPage["Signup Page"]:::ui
            QuizPage["Quiz Page"]:::ui
            ResultPage["Result Page"]:::ui
            SettingsPage["Settings Page"]:::ui
        end

        subgraph "Business Logic Layer" 
            direction TB
            AuthService["Authentication Service"]:::logic
            AuthGate["Auth Gate"]:::logic
            ThemeProvider["Theme Provider"]:::logic
            AppColors["App Colors"]:::logic
            Styles["Styles"]:::logic
        end

        subgraph "Data Layer" 
            direction TB
            QuizData["Quiz Data Model & Repository"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ExternalAuth["Auth Service (Firebase/Auth API)"]:::external
        ExternalQuizBackend["Quiz Backend/Database"]:::external
    end

    %% Connections
    AndroidShell -->|"embed"| Engine
    iOSShell -->|"embed"| Engine
    WebHost -->|"embed"| Engine
    LinuxWrapper -->|"embed"| Engine
    MacOSWrapper -->|"embed"| Engine
    WindowsWrapper -->|"embed"| Engine

    Engine -->|"render & runApp"| LoginPage
    Engine -->|"render & runApp"| SignupPage
    Engine -->|"render & runApp"| QuizPage
    Engine -->|"render & runApp"| ResultPage
    Engine -->|"render & runApp"| SettingsPage

    LoginPage -->|"calls"| AuthService
    SignupPage -->|"calls"| AuthService
    QuizPage -->|"calls"| QuizData
    ResultPage -->|"calls"| QuizData
    SettingsPage -->|"calls"| ThemeProvider

    AuthService -->|"method call"| QuizData
    AuthGate -->|"guards"| LoginPage
    ThemeProvider -->|"provides"| SettingsPage
    AppColors -->|"styles for"| LoginPage
    Styles -->|"styles for"| SignupPage

    AuthService -->|"HTTP request"| ExternalAuth
    QuizData -->|"REST/Firestore"| ExternalQuizBackend

    %% Click Events
    click AndroidShell "https://github.com/omarfettal/smartquiz/blob/main/android/app/src/main/kotlin/com/example/quiz/MainActivity.kt"
    click iOSShell "https://github.com/omarfettal/smartquiz/blob/main/ios/Runner/AppDelegate.swift"
    click WebHost "https://github.com/omarfettal/smartquiz/blob/main/web/index.html"
    click WebHost "https://github.com/omarfettal/smartquiz/blob/main/web/web_entrypoint.dart"
    click LinuxWrapper "https://github.com/omarfettal/smartquiz/blob/main/linux/main.cc"
    click MacOSWrapper "https://github.com/omarfettal/smartquiz/blob/main/macos/Runner/MainFlutterWindow.swift"
    click WindowsWrapper "https://github.com/omarfettal/smartquiz/blob/main/windows/runner/main.cpp"

    click Engine "https://github.com/omarfettal/smartquiz/blob/main/lib/main.dart"

    click LoginPage "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/login_page.dart"
    click SignupPage "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/signup_page.dart"
    click QuizPage "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/Quizpage.dart"
    click ResultPage "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/ResultPage.dart"
    click SettingsPage "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/settings_page.dart"

    click AuthService "https://github.com/omarfettal/smartquiz/blob/main/lib/utils/auth_service.dart"
    click AuthGate "https://github.com/omarfettal/smartquiz/blob/main/lib/utils/auth_gate.dart"
    click ThemeProvider "https://github.com/omarfettal/smartquiz/blob/main/lib/utils/themeprovider.dart"
    click AppColors "https://github.com/omarfettal/smartquiz/blob/main/lib/utils/app_colors.dart"
    click Styles "https://github.com/omarfettal/smartquiz/blob/main/lib/utils/styles.dart"

    click QuizData "https://github.com/omarfettal/smartquiz/blob/main/lib/screens/quizData.dart"

    %% Styles
    classDef platform fill:#cccccc,stroke:#333,stroke-width:1px
    classDef engine fill:#aaaaaa,stroke:#333,stroke-width:1px
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
