# zanz9/flutter_architecture architecture

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

- Interactive diagram: https://gitdiagram.com/zanz9/flutter_architecture
- Repository: https://github.com/zanz9/flutter_architecture

## Overview

##### Project type and purpose
- This is a mobile application built with Flutter, structured according to Clean Architecture principles.
- The core objective is to deliver a scalable, maintainable codebase with clear separation of concerns across presentation, domain, and data layers.

##### File structure
- Top-level:
- android/ and ios/ folders for native build configurations
- lib/ with main.dart and src/ for all Dart code
- assets/ for static resources
- Under lib/src:
- app/ holds application entry, flavor builds, runner
- core/ contains reusable modules: API client, dependency injection, theme, routing, localization, utilities, base classes, models, exceptions, widgets
- features/ holds feature modules; here only auth with data, domain, presentation subdirectories
- Recognize Clean Architecture boundaries: presentation → domain → data, plus a shared core.

##### README for additional insights
- It confirms three layers: Presentation (BLoC + UI), Domain (use cases, entities, repository interfaces), Data (concrete implementations, remote/local sources).
- Stacks: BLoC, Dio, GetIt/Injectable, GoRouter, Hive, Intl, etc.

##### Components
a. Main application shell (main.dart → runner)
b. Dependency Injection Container (GetIt/Injectable)
c. Presentation Layer
– UI Widgets, Screens, BLoC/Cubit components
– GoRouter navigation
d. Domain Layer
– Entities, Use Cases, Repository Interfaces
e. Data Layer
– Repository Implementations
– Remote Data Source (Dio HTTP Client, token interceptor)
– Local Data Source (Hive storage service)
f. Core Modules
– API client configuration
– Logging & error handling (Talker, Sentry)
– Localization module
g. External Services
– REST API endpoints
– Local storage (Hive)
– Third-party services (Firebase, geolocation, file picker)

##### Relationships and interactions
- Startup flow: main.dart → runner → configure DI → launch App widget
- Presentation requests a use case via injected view-controller or BLoC
- Use case calls repository interface
- Repository implementation picks either remote or local source
- Remote source uses Dio client → REST API
- Local source uses Hive → device storage
- Responses propagate back: data layer → domain → presentation → UI
- Navigation events handled by GoRouter
- Services logging errors to Talker/Sentry

##### Architectural patterns and design principles
- Clean Architecture (layered hexagon) – dependency rule inward
- BLoC for state management in presentation
- Repository pattern for data access
- Dependency Injection for decoupling components
- Code generation (Freezed, JSON Serializable, Injectable)
- Flavor builds for environment configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% App Initialization
    subgraph "App Initialization"
        Main["main.dart"]:::core
        Runner["runner.dart"]:::core
        Application["application.dart"]:::core
        Flavor["flavor_builds.dart"]:::core
    end

    %% Dependency Injection
    subgraph "Dependency Injection"
        DI["Injectable Service"]:::core
        DIConfig["injectable_service.config.dart"]:::core
        Manual["manual_register_services.dart"]:::core
        Proxy["service_register_proxy.dart"]:::core
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "UI & Widgets"
            Widgets["Custom Widgets"]:::presentation
        end
        subgraph "State Management"
            BaseBloc["base_bloc.dart"]:::presentation
            BaseBlocWidget["base_bloc_widget.dart"]:::presentation
            BaseCubit["base_cubit.dart"]:::presentation
            BaseCubitWidget["base_cubit_widget.dart"]:::presentation
            AuthBloc["auth_bloc.dart"]:::presentation
        end
        Pages["login_page.dart"]:::presentation
        Router["GoRouter"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Entity["login_entity.dart"]:::domain
        Request["login_request.dart"]:::domain
        RepoInterface["i_auth_repository.dart"]:::domain
        UseCase["use_case.dart"]:::domain
        Result["result.dart"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        RepoImpl["auth_repository_impl.dart"]:::data
        subgraph "Remote Data Source"
            IRemote["i_auth_remote.dart"]:::data
            RemoteImpl["auth_remote_impl.dart"]:::data
            DioClient["dio_client.dart"]:::data
            DioConfig["dio_config.dart"]:::data
            TokenInterceptor["token_interceptor.dart"]:::data
            Endpoints["endpoints.dart"]:::data
        end
        subgraph "Local Data Source"
            ILocal["i_auth_local.dart"]:::data
            LocalImpl["auth_local_impl.dart"]:::data
            StorageService["storage_service.dart"]:::data
            StorageServiceImpl["storage_service_impl.dart"]:::data
        end
    end

    %% Core Modules
    subgraph "Core Modules"
        APIConfig["API Client"]:::core
        Logging["Logging & Error Handling"]:::core
        Localization["Localization"]:::core
        Theming["Theming"]:::core
    end

    %% External Services
    subgraph "External Services"
        REST["REST API"]:::external
        Hive["Hive Storage"]:::external
        Firebase["Firebase & Utils"]:::external
    end

    %% Connections
    Main -->|calls| Runner
    Runner -->|initializes| Application
    Application -->|loads| Flavor
    Flavor -->|configures| DI

    DI -->|provides to| Widgets
    DI --> BaseBloc
    DI --> AuthBloc
    DI --> Router
    DI --> RepoImpl

    Widgets -->|dispatches| AuthBloc
    Pages -->|uses| AuthBloc
    AuthBloc -->|executes| UseCase
    UseCase -->|calls| RepoInterface
    RepoInterface -->|implemented by| RepoImpl
    RepoImpl -->|fetches from| RemoteImpl
    RepoImpl -->|fetches from| LocalImpl

    RemoteImpl -->|HTTP via| DioClient
    DioClient -->|configured by| DioConfig
    DioClient -->|intercepts| TokenInterceptor
    DioClient -->|targets| Endpoints
    RemoteImpl -->|calls| REST

    LocalImpl -->|uses| StorageServiceImpl
    StorageServiceImpl -->|backed by| Hive

    Logging -->|logs errors to| Firebase
    Localization -->|provides| Widgets
    Theming -->|styles| Widgets

    Router -->|navigates| Pages

    %% Click Events
    click Main "https://github.com/zanz9/flutter_architecture/blob/main/lib/main.dart"
    click Runner "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/app/runner.dart"
    click Application "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/app/application.dart"
    click Flavor "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/app/flavor_builds.dart"

    click DI "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/injectable/injectable_service.dart"
    click DIConfig "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/injectable/injectable_service.config.dart"
    click Manual "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/injectable/manual_register_services.dart"
    click Proxy "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/injectable/service_register_proxy.dart"

    click Widgets "https://github.com/zanz9/flutter_architecture/tree/main/lib/src/core/widgets/"
    click BaseBloc "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_bloc/bloc/base_bloc.dart"
    click BaseBlocWidget "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_bloc/bloc/base_bloc_widget.dart"
    click BaseCubit "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_bloc/cubit/base_cubit.dart"
    click BaseCubitWidget "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_bloc/cubit/base_cubit_widget.dart"
    click AuthBloc "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/presentation/bloc/auth_bloc.dart"
    click Pages "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/presentation/pages/login_page.dart"
    click Router "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/router/router.dart"

    click Entity "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/domain/entities/login_entity.dart"
    click Request "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/domain/requests/login_request.dart"
    click RepoInterface "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/domain/repositories/i_auth_repository.dart"
    click UseCase "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_use_case/use_case.dart"
    click Result "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/base/base_use_case/result.dart"

    click RepoImpl "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/data/repositories/auth_repository_impl.dart"
    click IRemote "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/data/sources/remote/i_auth_remote.dart"
    click RemoteImpl "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/data/sources/remote/auth_remote_impl.dart"
    click DioClient "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/api/client/dio/dio_client.dart"
    click DioConfig "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/api/client/dio/dio_config.dart"
    click TokenInterceptor "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/api/client/dio/token_interceptor.dart"
    click Endpoints "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/api/client/endpoints.dart"

    click ILocal "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/data/sources/local/i_auth_local.dart"
    click LocalImpl "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/features/auth/data/sources/local/auth_local_impl.dart"
    click StorageService "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/storage/storage_service.dart"
    click StorageServiceImpl "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/service/storage/storage_service_impl.dart"

    click Logging "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/utils/loggers/log.dart"
    click Localization "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/localization/generated/l10n.dart"
    click Theming "https://github.com/zanz9/flutter_architecture/blob/main/lib/src/core/theme/theme.dart"

    classDef presentation fill:#D0E6FF,stroke:#0366D6;
    classDef domain fill:#DFFFE0,stroke:#28A745;
    classDef data fill:#FFE8CC,stroke:#D15704;
    classDef core fill:#FFF4C1,stroke:#DBAB09;
    classDef external fill:#E2E2E2,stroke:#6A737D;
```
