# abhishekkx/army-institute-of-law-exam-app architecture

> Architecture diagram of the GitHub repository abhishekkx/army-institute-of-law-exam-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishekkx/army-institute-of-law-exam-app
- Repository: https://github.com/abhishekkx/army-institute-of-law-exam-app

## Overview

##### Project type and purpose
- This is a cross-platform mobile application built with Flutter/Dart.
- Purpose: Provide a practice-test environment for the Army Institute of Law entrance exam, with four timed sections, dynamic question loading via the Gemini API, offline fallbacks, immediate feedback, and responsive UI.

##### File structure
Top-level folders and files:
- android/ – Native Android project and Gradle build scripts for embedding the Flutter engine.
- lib/ – Main Dart code:
– main.dart: App entrypoint, API key config, runApp()
– models/: Data classes (e.g., Question)
– services/: Business logic, API integration (GeminiService) & mock fallback
– widgets/: UI components (QuestionWidget, SidebarWidget, etc.)
- test/: Widget tests
- pubspec.yaml / pubspec.lock: Flutter dependency management
- README.md: Project overview, features, setup, usage

##### README for additional insights
- Tech stack: Flutter SDK, Dart, flutter_gemini package, Material widgets, built-in StatefulWidget state management
- Architecture hints: Separation between UI (widgets), domain (models), and service (Gemini API + fallback logic)
- Key features: real-time question fetching, error retries, offline mode, timed sections, sidebar navigation

##### Components
a. Main components
- Mobile Device (iOS/Android) running the Flutter App
- Flutter Framework & Dart VM
- Presentation Layer: Widgets (StartScreen, QuizScreen, Sidebar, ScorecardDialog)
- State Management: StatefulWidgets managing UI state, timers, current question index
- Domain Layer: Question model, Section manager
- Service Layer:
– GeminiService: HTTP client to Gemini 2.0 Flash API, retry logic, JSON parsing
– MockQuestionProvider: Returns offline fallback questions
- Data Storage (optional): In-memory caches, local persistence if implemented
- External Service: Gemini API endpoint
- Native Android Host: Gradle scripts and AndroidManifest for app packaging

b. Relationships and interactions
1. User taps “Start Test” → Presentation layer triggers Service Layer to fetch first batch of questions.
2. GeminiService makes REST calls → receives JSON → maps to Question models → caches in memory.
3. On failure after retries → MockQuestionProvider returns fallback questions.
4. Presentation widgets consume Question models, render choices, handle user input.
5. Selection event → UI state updates (correct/wrong coloring) → state machine advances to next question.
6. SidebarWidget queries Section manager for current progress and allows jumps.
7. Timer in Presentation layer updates UI; on expiration triggers end-test flow → ScorecardDialog.
8. Native Android host/Flutter engine provides device capabilities (network, timers).

c. Architectural patterns and principles
– Layered architecture: Presentation → Domain → Service → External API
– Separation of concerns: UI code in widgets, pure data in models, async logic in services
– Fail-fast with retry and fallback (Circuit-Breaker style for API calls)
– Responsive design using MediaQuery/LayoutBuilder

d. Key technologies/frameworks/libraries
– Flutter SDK & Material Design widgets
– Dart language constructs (StatefulWidget, async/await)
– flutter_gemini package for Gemini API integration
– Gradle/Kotlin DSL for Android build
– JSON serialization (built-in or via package)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform Host Layer
    subgraph "Native Host Layer"
        direction TB
        MainActivity["MainActivity.kt"]:::host
        BuildScript["android/app/build.gradle.kts"]:::host
        ProjectSettings["android/settings.gradle.kts\nandroid/build.gradle.kts"]:::host
    end

    %% Flutter Engine Layer
    subgraph "Flutter Engine Layer"
        direction TB
        FlutterEngine["Flutter Engine & Dart VM"]:::engine
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Entrypoint["main.dart"]:::presentation
        StartScreen["StartScreen"]:::presentation
        QuizScreen["QuizScreen"]:::presentation
        QuestionWidget["QuestionWidget"]:::presentation
        SidebarWidget["SidebarWidget"]:::presentation
        ScorecardDialog["ScorecardDialog"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        QuestionModel["Question (question.dart)"]:::domain
        SectionManager["Section Manager"]:::domain
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        GeminiService["GeminiService"]:::service
        MockProvider["MockQuestionProvider"]:::service
        Cache["In-Memory Cache"]:::service
    end

    %% Assets & Tests
    subgraph "Assets & Testing"
        direction TB
        Icons["assets/icons/"]:::assets
        WidgetTest["widget_test.dart"]:::test
    end

    %% External Dependencies
    subgraph "External API"
        direction TB
        GeminiAPI["Gemini 2.0 Flash API"]:::external
    end

    %% Connections
    MainActivity -->|hosts| FlutterEngine
    BuildScript -->|configures| FlutterEngine
    ProjectSettings -->|settings| FlutterEngine

    FlutterEngine -->|runs| Entrypoint
    Entrypoint -->|navigates to| StartScreen
    StartScreen -->|Start Test event| QuizScreen
    QuizScreen -->|renders| QuestionWidget
    QuizScreen -->|renders| SidebarWidget
    QuizScreen -->|shows| ScorecardDialog

    QuestionWidget -->|requests questions| GeminiService
    QuestionWidget -->|displays models| QuestionModel
    SidebarWidget -->|queries| SectionManager
    ScorecardDialog -->|queries| SectionManager

    GeminiService -->|HTTP calls| GeminiAPI
    GeminiService -->|caches| Cache
    GeminiService -->|on failure after 3 retries| MockProvider
    MockProvider -->|returns fallback| QuestionModel

    Entrypoint -->|loads icons| Icons
    WidgetTest -->|tests| QuestionWidget
    WidgetTest -->|tests| SidebarWidget

    %% Click Events
    click Entrypoint "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/lib/main.dart"
    click QuestionModel "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/lib/models/question.dart"
    click GeminiService "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/lib/services/gemini_service.dart"
    click QuestionWidget "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/lib/widgets/question_widget.dart"
    click SidebarWidget "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/lib/widgets/sidebar_widget.dart"
    click MainActivity "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/android/app/src/main/kotlin/com/example/ail_test_app/MainActivity.kt"
    click BuildScript "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/android/app/build.gradle.kts"
    click ProjectSettings "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/android/settings.gradle.kts"
    click Icons "https://github.com/abhishekkx/army-institute-of-law-exam-app/tree/main/assets/icons/"
    click WidgetTest "https://github.com/abhishekkx/army-institute-of-law-exam-app/blob/main/test/widget_test.dart"

    %% Styles
    classDef host fill:#D8BFD8,stroke:#663399,color:#000
    classDef engine fill:#E0FFFF,stroke:#00CED1,color:#000
    classDef presentation fill:#ADD8E6,stroke:#4682B4,color:#000
    classDef domain fill:#98FB98,stroke:#228B22,color:#000
    classDef service fill:#FFDAB9,stroke:#FF8C00,color:#000
    classDef external fill:#FFC0CB,stroke:#FF4500,color:#000
    classDef assets fill:#FFFACD,stroke:#FFD700,color:#000
    classDef test fill:#F0E68C,stroke:#BDB76B,color:#000
```
