# stevenosse/flutter_kit architecture

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

- Interactive diagram: https://gitdiagram.com/stevenosse/flutter_kit
- Repository: https://github.com/stevenosse/flutter_kit

## Overview

##### Project Type and Purpose
- This is an opinionated, feature-first Flutter starter kit for building cross-platform (iOS/Android) mobile apps.
- It provides a preconfigured architecture covering UI, state management, routing, theming, internationalization, HTTP data sources, code generation, and basic utilities.

##### File Structure Analysis
- Top-level:
- android/ & ios/ – native project wrappers
- lib/ – application code
- assets/ – fonts and images
- test/ – widget/unit test stubs
- lib/src/:
- core/ – app initialization, environment config, i18n, routing, theming
- datasource/ – HTTP client setup (Dio), API models, repositories
- features/ – feature-scoped folders (e.g., login: UI + logic)
- shared/ – reusable widgets, extensions, service locator, storage/logger services
- Codegen: build_runner + flutter_gen for assets and intl_utils for translations.
- Build & CI: Makefile, GitHub Actions (static analysis).

##### Key Architectural Patterns
- Layered architecture (Presentation → Domain/Logic → Data)
- Feature-first folder structure
- Repository pattern for data access
- ChangeNotifier-based state management (controllers)
- Dependency injection via a service locator
- Auto_route for declarative navigation
- Material 3 theming and intl_utils for i18n

##### Main Components
A. Platform Layer
- Android & iOS native shells
- Flutter engine / Dart VM
B. Core Application
- main.dart → AppInitializer → Application widget
- Environment config
- Routing (AppRouter)
- i18n (intl generated code, ARB files)
C. Presentation Layer
- Screens (e.g., LoginScreen)
- Widgets & shared components (atoms, buttons, dialogs)
- Navigation actions (router.push/pop)
D. Business Logic Layer
- Controllers (ChangeNotifier classes)
- State classes
- ViewModel-style binding between UI and controllers
E. Data Layer
- Repositories (e.g., ExampleRepository)
- API models (ApiResponse)
- HTTP client utilities (DioConfig, HttpUtil)
F. Services & Utilities
- Storage services (local/in-memory)
- Logging service
- ServiceLocator registration
G. Code Generation & Build Tools (side note)
- flutter_gen (assets.gen.dart)
- intl_utils (messages_all.dart)
H. External Dependencies
- Remote API endpoints
- Pub.dev packages: auto_route, dio, intl_utils, flutter_gen

##### Relationships and Data Flow
1. App starts → main.dart calls AppInitializer → registers services in ServiceLocator
2. Application builds → injects AppRouter, Theme, Localization delegates
3. User navigates to a Feature Screen → Router instantiates Screen widget
4. UI widget obtains its Controller from ServiceLocator or Provider
5. Controller invokes Repository methods → uses HttpUtil/Dio to make network calls → parses ApiResponse → returns domain models
6. Controller updates its state → UI listens to ChangeNotifier → rebuilds widgets
7. Services like LocalStorage can be used by Repositories or Controllers for caching/ persistence
8. Shared components and extensions are leveraged by multiple features

## Diagram (Mermaid)

```mermaid
graph TD
    %% Platform Layer
    subgraph "Platform Layer"
        direction TB
        AndroidShell["Android Shell"]:::platform
        iOSShell["iOS Shell"]:::platform
        FlutterEngine["Flutter Engine / Dart VM"]:::platform
    end

    %% Core Application Layer
    subgraph "Core Application" 
        direction TB
        Main["main.dart"]:::core
        AppInit["AppInitializer"]:::core
        Application["Application Widget"]:::core
        EnvConfig["Environment Config"]:::core
        AppRouter["AppRouter"]:::core
        Theming["AppTheme & ColorSchemes"]:::core
        I18n["i18n (messages_all / intl)"]:::core
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        LoginScreen["LoginScreen UI"]:::ui
        SharedAtoms["BasicCard / LabeledDivider"]:::ui
        SharedButtons["Button"]:::ui
        SharedDialogs["Confirmation / Informative / Loading Dialogs"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        LoginController["LoginController (ChangeNotifier)"]:::logic
        LoginState["LoginState"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DioConfig["DioConfig"]:::data
        HttpUtil["HttpUtil"]:::data
        ExampleAPI["ExampleAPI"]:::data
        ApiResponse["ApiResponse Model"]:::data
        BaseRepo["BaseRepository"]:::data
        ExampleRepo["ExampleRepository"]:::data
    end

    %% Services & Utilities
    subgraph "Services & Utilities"
        direction TB
        ServiceLocator["ServiceLocator"]:::service
        AppLogger["AppLogger"]:::service
        StorageInterface["Storage Interface"]:::service
        InMemoryStorage["InMemoryStorage"]:::service
        LocalStorage["LocalStorage"]:::service
    end

    %% Code Generation & Build Tools
    subgraph "Code Generation & Build Tools"
        direction TB
        AssetGen["assets.gen.dart"]:::codegen
        IntlGen["messages_all.dart"]:::codegen
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        RemoteAPI["Remote API Endpoints"]:::external
        PubPackages["Pub.dev Packages"]:::external
    end

    %% Initialization Flow
    AndroidShell -->|launches| FlutterEngine
    iOSShell -->|launches| FlutterEngine
    FlutterEngine -->|runs| Main
    Main -->|calls| AppInit
    AppInit -->|registers| ServiceLocator
    AppInit -->|initializes| EnvConfig
    AppInit -->|initializes| AppRouter
    AppInit -->|initializes| Theming
    AppInit -->|initializes| I18n
    AppInit -->|builds| Application

    %% Application Injection
    Application -->|"injects Router"| AppRouter
    Application -->|"injects Theme"| Theming
    Application -->|"injects Localization"| I18n

    %% UI Navigation & Flow
    Application -->|"navigates to"| LoginScreen
    LoginScreen -->|gets controller| LoginController
    LoginController -->|uses state| LoginState
    LoginController -->|calls| ExampleRepo
    ExampleRepo -->|extends| BaseRepo
    ExampleRepo -->|uses| ExampleAPI
    ExampleAPI -->|uses| HttpUtil
    HttpUtil -->|configures| DioConfig
    ExampleAPI -->|calls| RemoteAPI
    RemoteAPI -->|returns data| ApiResponse
    ApiResponse -->|parsed by| ExampleRepo
    ExampleRepo -->|returns model| LoginController
    LoginController -->|notifies| LoginScreen

    %% Shared Components Usage
    LoginScreen -->|uses| SharedAtoms
    LoginScreen -->|uses| SharedButtons
    LoginScreen -->|uses| SharedDialogs

    %% Services Flow
    ServiceLocator -->|provides| AppLogger
    ServiceLocator -->|provides| StorageInterface
    StorageInterface -->|implemented by| InMemoryStorage
    StorageInterface -->|implemented by| LocalStorage
    LoginController -->|may use| AppLogger
    ExampleRepo -->|may use| LocalStorage

    %% Codegen Integration
    AssetGen -->|generates| SharedAtoms
    IntlGen -->|generates| I18n

    %% External Dependencies
    PubPackages -->|provide| AppRouter
    PubPackages -->|provide| DioConfig
    PubPackages -->|provide| IntlGen

    %% Click Events
    click AndroidShell "https://github.com/stevenosse/flutter_kit/tree/master/android/"
    click iOSShell "https://github.com/stevenosse/flutter_kit/tree/master/ios/"
    click Main "https://github.com/stevenosse/flutter_kit/blob/master/lib/main.dart"
    click AppInit "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/app_initializer.dart"
    click Application "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/application.dart"
    click EnvConfig "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/environment.dart"
    click AppRouter "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/routing/app_router.dart"
    click Theming "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/theme/app_theme.dart"
    click I18n "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/i18n/intl/messages_all.dart"
    click LoginScreen "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/features/login/ui/login_screen.dart"
    click SharedAtoms "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/components/atoms/basic_card.dart"
    click SharedButtons "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/components/buttons/button.dart"
    click SharedDialogs "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/components/dialogs/confirmation_dialog.dart"
    click LoginController "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/features/login/logic/login_controller.dart"
    click LoginState "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/features/login/logic/login_state.dart"
    click DioConfig "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/http/dio_config.dart"
    click HttpUtil "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/http/http_util.dart"
    click ExampleAPI "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/http/example_api.dart"
    click ApiResponse "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/models/api_response/api_response.dart"
    click BaseRepo "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/repositories/base_repository.dart"
    click ExampleRepo "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/datasource/repositories/example_repository.dart"
    click ServiceLocator "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/locator.dart"
    click AppLogger "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/services/app_logger.dart"
    click StorageInterface "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/services/storage/storage.dart"
    click InMemoryStorage "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/services/storage/in_memory_storage.dart"
    click LocalStorage "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/shared/services/storage/local_storage.dart"
    click AssetGen "https://github.com/stevenosse/flutter_kit/blob/master/lib/gen/assets.gen.dart"
    click IntlGen "https://github.com/stevenosse/flutter_kit/blob/master/lib/src/core/i18n/intl/messages_all.dart"
    click PubPackages "https://github.com/stevenosse/flutter_kit/blob/master/pubspec.yaml"

    %% Styles
    classDef platform fill:#d3d3d3,stroke:#888,stroke-width:1px;
    classDef core fill:#a3c4f3,stroke:#0366d6,stroke-width:1px;
    classDef ui fill:#b3e5fc,stroke:#0288d1,stroke-width:1px;
    classDef logic fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
    classDef data fill:#ffe0b2,stroke:#f57c00,stroke-width:1px;
    classDef service fill:#e1bee7,stroke:#7b1fa2,stroke-width:1px;
    classDef codegen fill:#fff9c4,stroke:#fbc02d,stroke-width:1px;
    classDef external fill:#eeeeee,stroke:#666666,stroke-width:1px;
```
