# alexisl61/fluttertemplate architecture

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

- Interactive diagram: https://gitdiagram.com/alexisl61/fluttertemplate
- Repository: https://github.com/alexisl61/fluttertemplate

## Overview

##### Project type and purpose
- This is a cross-platform Flutter application template with built-in dependency injection (get_it) and an MVVM folder architecture.
- It targets Android, iOS, Linux, macOS, Windows, and web, but the heart of the logic lives in lib/.

##### File structure
- Top-level directories (android, ios, linux, macos, web, windows) contain platform-specific boilerplate generated by Flutter.
- The lib/ directory contains the core architecture:
- components/ (atoms, molecules, organisms) – reusable UI widgets
- pages/ – full-screen views, each paired with a ViewModel
- model/ – data classes + MVVM core (ViewModel base, events, observer)
- providers/ – environment split (Dummy vs Live) and dependency wiring
- services/ – data retrieval logic (dummy, live, core)
- repositories/ – combine services + transformers
- transformers/ – map raw data into data classes
- utils/ – extensions and helper functions
- Configuration files: pubspec.yaml for dependencies, analysis_options.yaml for lint rules.

##### Insights from the README
- Two entry points (main_dummy.dart, main_live.dart) switch the provider environment.
- Architectural flow: Page ↔ ViewModel → Repository → {Transformer, Service} → DataClass.
- DI is handled by get_it inside the provider files.

a. Main Components
1. Flutter Shell (the engine & platform runner across Android, iOS, etc.)
2. UI Layer
– Pages (full screens)
– Components (atoms, molecules, organisms)
3. Presentation Logic
– ViewModels (one per page or component when complex)
4. Data Layer
– Repositories
– Services (dummy or live implementations)
– Transformers
– Data Classes (models)
5. Dependency Injection Container (get_it)
6. External API (if Live provider) or Static Data (Dummy provider)

b. Relationships & Data Flow
- Pages render Components and bind to their ViewModel.
- Components may send UI events back to their parent ViewModel.
- ViewModel requests data from a Repository.
- Repository invokes Service and Transformer in parallel or sequence.
- Repository returns Data Classes back to ViewModel, which notifies the Page.
- Provider (Dummy or Live) at app start configures get_it with the correct Repository implementations.

c. Architectural Patterns & Principles
- MVVM with explicit ViewModel for state and event management.
- Dependency Injection via get_it, configured by environment-specific providers.
- Layered architecture: Presentation → Domain (ViewModel) → Data (Repo/Service/Transformer).
- Component-based UI (atomic design: atoms → molecules → organisms).

d. Key Technologies & Frameworks
- Flutter SDK (Dart)
- get_it for DI
- Provider pattern for environment switching
- Dart built_ins and extensions (utils)

##### Don’t Overthink—Capture Every Piece
- Directories from lib/ that map to a runtime component.
- Provider switch (Dummy vs Live) clearly at startup.
- How utility extensions and transformers fit into the data flow.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Platforms
    subgraph "Flutter Engine & Platform Runners"
        direction TB
        Android["android/"]:::external
        iOS["ios/"]:::external
        Linux["linux/"]:::external
        macOS["macos/"]:::external
        Windows["windows/"]:::external
        Web["web/"]:::external
    end
    click Android "https://github.com/alexisl61/fluttertemplate/tree/main/android/"
    click iOS "https://github.com/alexisl61/fluttertemplate/tree/main/ios/"
    click Linux "https://github.com/alexisl61/fluttertemplate/tree/main/linux/"
    click macOS "https://github.com/alexisl61/fluttertemplate/tree/main/macos/"
    click Windows "https://github.com/alexisl61/fluttertemplate/tree/main/windows/"
    click Web "https://github.com/alexisl61/fluttertemplate/tree/main/web/"

    %% Entry Points
    subgraph "Entry Points"
        direction TB
        Main["lib/main.dart"]:::external
        DummyMain["lib/main_dummy.dart"]:::external
        LiveMain["lib/main_live.dart"]:::external
    end
    click Main "https://github.com/alexisl61/fluttertemplate/blob/main/lib/main.dart"
    click DummyMain "https://github.com/alexisl61/fluttertemplate/blob/main/lib/main_dummy.dart"
    click LiveMain "https://github.com/alexisl61/fluttertemplate/blob/main/lib/main_live.dart"

    Android --> FlutterShell
    iOS --> FlutterShell
    Linux --> FlutterShell
    macOS --> FlutterShell
    Windows --> FlutterShell
    Web --> FlutterShell

    FlutterShell["Flutter Shell"]:::external
    FlutterShell --> Main
    FlutterShell --> DummyMain
    FlutterShell --> LiveMain

    %% DI Container & Providers
    subgraph "Dependency Injection"
        direction TB
        DI["get_it Container"]:::domain
        Provider["lib/providers/provider.dart"]:::domain
        DummyProv["lib/providers/dummy_provider.dart"]:::domain
        LiveProv["lib/providers/live_provider.dart"]:::domain
    end
    click Provider "https://github.com/alexisl61/fluttertemplate/blob/main/lib/providers/provider.dart"
    click DummyProv "https://github.com/alexisl61/fluttertemplate/blob/main/lib/providers/dummy_provider.dart"
    click LiveProv "https://github.com/alexisl61/fluttertemplate/blob/main/lib/providers/live_provider.dart"

    Main --> Provider
    DummyMain --> DummyProv
    LiveMain --> LiveProv
    Provider --> DI
    DummyProv --> DI
    LiveProv --> DI

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        Pages["Pages"]:::presentation
        Components["Components"]:::presentation
        ExamplePage["ExamplePage"]:::presentation
        ExamplePageVM["ExampleViewModel"]:::domain
    end
    click ExamplePage "https://github.com/alexisl61/fluttertemplate/blob/main/lib/pages/example/example_view.dart"
    click ExamplePageVM "https://github.com/alexisl61/fluttertemplate/blob/main/lib/pages/example/example_view_model.dart"
    DI --> ExamplePageVM
    ExamplePageVM --> ExamplePage
    ExamplePage --> Pages
    Components --> Pages

    subgraph "Atomic Components"
        direction TB
        Atoms["Atoms"]:::presentation
        Molecules["Molecules"]:::presentation
        Organisms["Organisms"]:::presentation
    end
    click Atoms "https://github.com/alexisl61/fluttertemplate/tree/main/lib/components/atoms/"
    click Molecules "https://github.com/alexisl61/fluttertemplate/tree/main/lib/components/molecules/"
    click Organisms "https://github.com/alexisl61/fluttertemplate/tree/main/lib/components/organisms/"
    Components --> Atoms
    Components --> Molecules
    Components --> Organisms

    %% Domain (MVVM Core)
    subgraph "MVVM Core" 
        direction TB
        BaseVM["view_model.dart"]:::domain
        Events["view_event.dart"]:::domain
        WidgetObs["widget_event_observer.dart"]:::domain
        SpecificEvents["view_events/*.dart"]:::domain
    end
    click BaseVM "https://github.com/alexisl61/fluttertemplate/blob/main/lib/model/mvvm/view_model.dart"
    click Events "https://github.com/alexisl61/fluttertemplate/blob/main/lib/model/mvvm/view_event.dart"
    click WidgetObs "https://github.com/alexisl61/fluttertemplate/blob/main/lib/model/mvvm/widget_event_observer.dart"
    click SpecificEvents "https://github.com/alexisl61/fluttertemplate/tree/main/lib/model/mvvm/view_events/"
    BaseVM --> ExamplePageVM
    Events --> BaseVM
    WidgetObs --> ExamplePageVM
    SpecificEvents --> Events

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Repo["ExampleRepository"]:::data
        ServiceIface["example_service.dart"]:::data
        DummySvc["dummy_example_service.dart"]:::data
        LiveSvc["live_example_service.dart"]:::data
        Transformer["example_transformer.dart"]:::data
        ModelClass["example_class.dart"]:::data
    end
    click Repo "https://github.com/alexisl61/fluttertemplate/blob/main/lib/repositories/example_repository.dart"
    click ServiceIface "https://github.com/alexisl61/fluttertemplate/blob/main/lib/services/example/example_service.dart"
    click DummySvc "https://github.com/alexisl61/fluttertemplate/blob/main/lib/services/example/dummy_example_service.dart"
    click LiveSvc "https://github.com/alexisl61/fluttertemplate/blob/main/lib/services/example/live_example_service.dart"
    click Transformer "https://github.com/alexisl61/fluttertemplate/blob/main/lib/transformers/example_transformer.dart"
    click ModelClass "https://github.com/alexisl61/fluttertemplate/blob/main/lib/model/class/example_class.dart"

    ExamplePageVM --> Repo
    Repo --> ServiceIface
    ServiceIface --> DummySvc
    ServiceIface --> LiveSvc
    Repo --> Transformer
    Transformer --> ModelClass
    ServiceIface -->|"fetch raw data"| ExternalAPI
    DummySvc -->|"load static data"| StaticData

    %% External Data Sources
    subgraph "Data Sources"
        direction TB
        ExternalAPI["External API"]:::external
        StaticData["Static Data"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        BoolUtils["boolean_utils.dart"]:::data
        NullUtils["null_utils.dart"]:::data
        StringUtils["string_utils.dart"]:::data
    end
    click BoolUtils "https://github.com/alexisl61/fluttertemplate/blob/main/lib/utils/boolean_utils.dart"
    click NullUtils "https://github.com/alexisl61/fluttertemplate/blob/main/lib/utils/null_utils.dart"
    click StringUtils "https://github.com/alexisl61/fluttertemplate/blob/main/lib/utils/string_utils.dart"
    Transformer --> BoolUtils
    Transformer --> NullUtils
    Transformer --> StringUtils

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#005B9F,color:#005B9F
    classDef domain fill:#DFF2D8,stroke:#3C763D,color:#3C763D
    classDef data fill:#FEE7CD,stroke:#E98A3C,color:#E98A3C
    classDef external fill:#E0E0E0,stroke:#757575,color:#424242
```
