# leleocastro/flutter_clean_arch architecture

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

- Interactive diagram: https://gitdiagram.com/leleocastro/flutter_clean_arch
- Repository: https://github.com/leleocastro/flutter_clean_arch

## Overview

##### Project type and purpose
- This is a multi‐platform Flutter application (mobile, web, desktop) built using Domain-Driven Design (DDD) principles and the BLoC pattern.
- Its purpose is to serve as a template or base “micro-application” that layers UI, domain logic, and data access cleanly.

##### File structure
- Top-level folders (android, ios, linux, macos, windows, web) hold the platform-specific Flutter shells and generated native code.
- The heart of the code lives under lib/src and splits into three layers:
– ui: pages, widgets, and BLoC components
– domain: entities, repository interfaces, and use cases
– data: data sources, data models, and repository implementations
- A shared folder holds cross-cutting utilities (error wrappers, extensions).
- Tests mirror the lib/src hierarchy, demonstrating a test-driven structure.

##### README for insights
- The README outlines the three DDD layers (UI, Domain, Data) and shows an example image of the layered hierarchy.
- It confirms the use of BLoC for state management and a clear contracts-and-implementations approach for the data layer.

##### Key components
a. Presentation Layer (UI)
– Flutter Widgets / Pages (e.g., MeuPage)
– BLoC components (MeuBloc, MeuAppBarBloc, MeuTextFieldBloc)
b. Domain Layer
– Entities (AddressEntity)
– Repository interfaces (MeuRepository)
– Use cases (GetAddressUseCase)
c. Data Layer
– Data sources (MeuDataSource)
– Data models (AddressModel)
– Repository implementations (MeuRepositoryImpl)
d. Shared / Core
– Error handling (BaseError, ResultWrapper)
– Extensions, base states
e. Platform Adapters
– Flutter engine / method channels (android/ios/… folders)
– Asset bundles (assets/images)
f. External Services
– Remote API endpoints (implied by data source)

##### Relationships and data flow
- UI Widgets → dispatch events to BLoC
- BLoC → invokes Use Case(s) in Domain
- Use Case → calls Repository interface
- Repository Impl → uses Data Source to fetch or persist models
- Data Source → external API or local cache
- Results flow back up through Repository → Use Case → BLoC → UI

##### Architectural patterns and principles
- Layered (Onion/Hexagonal) architecture with clear boundaries
- Dependency inversion: domain layer depends only on interfaces
- BLoC pattern for unidirectional data flow and state management
- Port-and-adapter approach for platform and external service integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Page["MeuPage"]:::ui
        Bloc["MeuBloc"]:::bloc
        AppBarWidget["MeuAppBar"]:::ui
        AppBarBloc["MeuAppBarBloc"]:::bloc
        TextFieldWidget["MeuTextField"]:::ui
        TextFieldBloc["MeuTextFieldBloc"]:::bloc
        SharedRow["MeuRow"]:::ui
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        Entity["AddressEntity"]:::domain
        RepoIface["MeuRepository"]:::domain
        UseCase["GetAddressUseCase"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RepoImpl["MeuRepositoryImpl"]:::data
        DataSource["MeuDataSource"]:::data
        Model["AddressModel"]:::data
    end

    %% Shared/Core
    subgraph "Shared / Core"
        direction TB
        Error["BaseError"]:::core
        Wrapper["ResultWrapper"]:::core
        BaseState["BaseState"]:::core
        Ext["StringExtensions"]:::core
    end

    %% Application Bootstrap
    subgraph "Application"
        direction TB
        App["MeuApp (Entry & Routing)"]:::infra
        Module["MeuModule (Dependency Module)"]:::infra
    end

    %% Platform Adapters / Shells
    subgraph "Platform Adapters / Shells"
        direction TB
        Android["Android"]:::infra
        IOS["iOS"]:::infra
        Linux["Linux"]:::infra
        MacOS["macOS"]:::infra
        Windows["Windows"]:::infra
        Web["Web"]:::infra
    end

    %% Assets
    subgraph "Assets"
        direction TB
        Images["assets/images"]:::infra
    end

    %% Relationships
    Page -->|"dispatch event"| Bloc
    AppBarWidget -->|"dispatch event"| AppBarBloc
    TextFieldWidget -->|"dispatch event"| TextFieldBloc

    Bloc -->|"calls"| UseCase
    AppBarBloc -->|"calls"| UseCase
    TextFieldBloc -->|"calls"| UseCase

    UseCase -->|"depends on"| RepoIface
    RepoImpl -->|"implements"| RepoIface
    RepoImpl -->|"calls"| DataSource
    DataSource -->|"returns model"| Model
    Model -->|"maps to entity"| Entity

    RepoImpl -->|"wraps result"| Wrapper
    Wrapper -->|"handles error"| Error
    BaseState -->|"extends BLoC states"| Bloc

    App -->|"initializes"| Page
    Module -->|"provides dependencies to"| Bloc
    Module -->|"provides dependencies to"| UseCase
    Module -->|"provides dependencies to"| RepoImpl

    %% Click Events
    click Page "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/meu_page.dart"
    click Bloc "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/meu_bloc.dart"
    click AppBarWidget "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/components/meu_appbar/meu_appbar.dart"
    click AppBarBloc "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/components/meu_appbar/meu_appbar_bloc.dart"
    click TextFieldWidget "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/components/meu_textfield/meu_textfield.dart"
    click TextFieldBloc "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/pages/meu/components/meu_textfield/meu_textfield_bloc.dart"
    click SharedRow "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/ui/shared_components/meu_row.dart"
    click Entity "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/domain/entities/address_entity.dart"
    click RepoIface "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/domain/repositories/meu_repository.dart"
    click UseCase "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/domain/usecases/get_address_usecase.dart"
    click DataSource "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/data/datasources/meu_datasource.dart"
    click Model "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/data/models/address_model.dart"
    click RepoImpl "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/data/repositories/meu_repository_impl.dart"
    click Error "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/shared/base_error.dart"
    click Wrapper "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/shared/result_wrapper.dart"
    click BaseState "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/shared/base_state.dart"
    click Ext "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/shared/string_extensions.dart"
    click App "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/meu_app.dart"
    click Module "https://github.com/leleocastro/flutter_clean_arch/blob/main/lib/src/meu_module.dart"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef bloc fill:#b3e5fc,stroke:#039be5,color:#01579b;
    classDef domain fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef data fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef core fill:#fff9c4,stroke:#fdd835,color:#f57f17;
    classDef infra fill:#e0e0e0,stroke:#757575,color:#212121;
```
