# hungps/flutter_starter architecture

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

- Interactive diagram: https://gitdiagram.com/hungps/flutter_starter
- Repository: https://github.com/hungps/flutter_starter

## Overview

##### Main Components

a. Platform-specific Shells & Configuration:
- Platforms: Android, iOS, web, desktop (Linux, macOS, Windows)
- Flavor Management: Different entry files (lib/main_dev.dart, lib/main_staging.dart, lib/main_production.dart) and flavor configurations (lib/flavors.dart, flavorizr.yaml) to manage environment-specific settings.
- Build Tools/Infrastructure: FVM configuration, Mason bricks (located under bricks/ and mason.yaml) for rapid code generation, and platform-specific directories that detail asset usage and build scripts.

b. Presentation Layer:
- Internationalization: Languages support with translations (lib/presenter/languages, translations in JSON files) and a script to generate translation keys.

c. Data Layer:
- Entities & Data Models: Under lib/data/entities, you have core models (for accounts, login parameters, etc.) with accompanying generated files.
- Repositories: e.g. the auth_repository defined in lib/data/repositories/auth_repository, managing the coordination between data sources.
- Data Sources: Separated into local (lib/data/sources/local) and network (lib/data/sources/network) layers, including integration with networking libraries (Dio is in use).
- Use Cases: Business logic like login and verifying login status is abstracted in lib/data/usecases.

d. Core & Cross-cutting Concerns:
- Core Logic: Common logic elements (e.g., exception handling in lib/core/exception.dart, common use cases in lib/core/use_case.dart).
- Dependency Injection: Setup in lib/di.dart and generated configuration in lib/di.config.dart to wire components.
- State Management: Bloc implementations for authentication and settings in lib/data/states, following the bloc pattern (auth_bloc, settings_bloc, etc.).

e. Auxiliary Services:
- Services such as OAuth token management (lib/services/oauth_token_manager) to manage external authentication tokens.

##### Relationships and Interactions

- UI Interaction Flow: The user interacts with the Presentation layer. Pages in the presenter dispatch events to blocs (e.g., login_bloc, splash_bloc) which then call use cases in the Data layer.
- Business Logic Flow: Use cases use repositories which abstract access to multiple data sources. Local and network sources feed data upstream, and exceptions are propagated via the core logic.
- Dependency Injection: DI (using lib/di files) is central to wiring up state management components, repositories, services, and use cases.
- Environment & Flavor Management: Different main entry points (dev, staging, production) and configurations allow the system to select the correct resources and endpoints based on the build flavor.
- Code Generation: The bricks and Mason CLI scripts support generating new modules (like bloc pages) and updating translation keys, ensuring consistency across the architecture.

##### Architectural Patterns and Technologies

- Bloc/State Management: Use of blocs to manage state transitions across authentication and settings workflows.
- MVVM/MVC or Clean Architecture: The separation of Presentation, Domain (use cases), and Data layers points to a Clean Architecture approach.
- Cross-Platform Design: Flutter structure supports multiple platforms with shared business logic, while platform-specific folders (android, ios, etc.) deal with native configurations.
- Internationalization: Integration of easy_localization to drive multi-language support.
- Dependency Injection: Use of DI to improve modularity and testability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform-Specific Shells & Configuration
    subgraph "Platform-Specific Shells & Configuration"
        direction TB
        P1["Main Dev (Entry)"]:::platform
        P2["Main Staging (Entry)"]:::platform
        P3["Main Production (Entry)"]:::platform
        P4a["Flavor Config (lib/flavors.dart)"]:::platform
        P4b["Flavor Config (flavorizr.yaml)"]:::platform
        PD1["Android (Directory)"]:::platform
        PD2["iOS (Directory)"]:::platform
        PD3["Web (Directory)"]:::platform
        PD4["Linux (Directory)"]:::platform
        PD5["macOS (Directory)"]:::platform
        PD6["Windows (Directory)"]:::platform
        P6a["Build Tool (.fvmrc)"]:::platform
        P6b["Bricks & Mason (bricks/ & mason.yaml)"]:::platform
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        PR1["App UI (app.dart)"]:::presentation
        PR2["Pages"]:::presentation
        PR3["Navigation"]:::presentation
        PR4["Themes"]:::presentation
        PR5["Widgets"]:::presentation
        PR6["Internationalization (languages)"]:::presentation
        PR7["Translations"]:::presentation
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        D1["Entities & Models"]:::dataLayer
        D2["Auth Repository"]:::dataLayer
        D3["Local Data Source"]:::dataLayer
        D4["Network Data Source"]:::dataLayer
        D5["Use Cases"]:::dataLayer
        D6["State Management (Blocs)"]:::dataLayer
    end

    %% Core & Dependency Injection
    subgraph "Core & Dependency Injection"
        direction TB
        C1a["Exception Handling"]:::core
        C1b["Common Use Cases"]:::core
        C2a["DI Setup (lib/di.dart)"]:::core
        C2b["DI Config (lib/di.config.dart)"]:::core
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        A1["OAuth Token Management"]:::auxiliary
    end

    %% Relationships

    %% Platform configuration flows into DI
    P1 -->|"configures"| C2a
    P2 -->|"configures"| C2a
    P3 -->|"configures"| C2a
    P4a -->|"provides"| C2a
    P4b -->|"provides"| C2a
    PD1 --- C2a
    PD2 --- C2a
    PD3 --- C2a
    PD4 --- C2a
    PD5 --- C2a
    PD6 --- C2a
    P6a -->|"automation"| PR1
    P6b -->|"scaffolds"| PR1

    %% DI wiring to other layers
    C2a -->|"injects"| D6
    C2a -->|"injects"| D2
    C2a -->|"injects"| A1

    %% Presentation to Data flow
    PR2 -->|"triggers"| D6
    D6 -->|"calls"| D5
    D5 -->|"uses"| D2
    D2 -->|"accesses"| D3
    D2 -->|"accesses"| D4
    D2 -->|"errors handled by"| C1a

    %% UI and Internationalization
    PR1 -->|"displays"| PR2
    PR1 --> PR7
    PR6 -->|"supports"| PR7

    %% Core & DI internal linkage
    C2a --> C2b

    %% Styles
    classDef platform fill:#f9c74f,stroke:#333,stroke-width:2px,color:#000;
    classDef presentation fill:#90be6d,stroke:#333,stroke-width:2px,color:#000;
    classDef dataLayer fill:#f94144,stroke:#333,stroke-width:2px,color:#fff;
    classDef core fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef auxiliary fill:#277da1,stroke:#333,stroke-width:2px,color:#fff;

    %% Click Events for Platform-Specific Shells & Configuration
    click P1 "https://github.com/hungps/flutter_starter/blob/develop/lib/main_dev.dart"
    click P2 "https://github.com/hungps/flutter_starter/blob/develop/lib/main_staging.dart"
    click P3 "https://github.com/hungps/flutter_starter/blob/develop/lib/main_production.dart"
    click P4a "https://github.com/hungps/flutter_starter/blob/develop/lib/flavors.dart"
    click P4b "https://github.com/hungps/flutter_starter/blob/develop/flavorizr.yaml"
    click PD1 "https://github.com/hungps/flutter_starter/tree/develop/android/"
    click PD2 "https://github.com/hungps/flutter_starter/tree/develop/ios/"
    click PD3 "https://github.com/hungps/flutter_starter/tree/develop/web/"
    click PD4 "https://github.com/hungps/flutter_starter/tree/develop/linux/"
    click PD5 "https://github.com/hungps/flutter_starter/tree/develop/macos/"
    click PD6 "https://github.com/hungps/flutter_starter/tree/develop/windows/"
    click P6a "https://github.com/hungps/flutter_starter/blob/develop/.fvmrc"
    click P6b "https://github.com/hungps/flutter_starter/tree/develop/bricks/"

    %% Click Events for Presentation Layer
    click PR1 "https://github.com/hungps/flutter_starter/blob/develop/lib/presenter/app.dart"
    click PR2 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/pages"
    click PR3 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/navigation"
    click PR4 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/themes"
    click PR5 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/widgets"
    click PR6 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/languages"
    click PR7 "https://github.com/hungps/flutter_starter/tree/develop/lib/presenter/languages/translations"

    %% Click Events for Data Layer
    click D1 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/entities"
    click D2 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/repositories/auth_repository"
    click D3 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/sources/local"
    click D4 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/sources/network"
    click D5 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/usecases"
    click D6 "https://github.com/hungps/flutter_starter/tree/develop/lib/data/states"

    %% Click Events for Core & Dependency Injection
    click C1a "https://github.com/hungps/flutter_starter/blob/develop/lib/core/exception.dart"
    click C1b "https://github.com/hungps/flutter_starter/blob/develop/lib/core/use_case.dart"
    click C2a "https://github.com/hungps/flutter_starter/blob/develop/lib/di.dart"
    click C2b "https://github.com/hungps/flutter_starter/blob/develop/lib/di.config.dart"

    %% Click Events for Auxiliary Services
    click A1 "https://github.com/hungps/flutter_starter/tree/develop/lib/services/oauth_token_manager"
```
