# mahmoudalbndkji/flutter-clean-architecture-tdd-template architecture

> Architecture diagram of the GitHub repository mahmoudalbndkji/flutter-clean-architecture-tdd-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template
- Repository: https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template

## Overview

##### Project type and purpose
- This is a Flutter mobile application template built with a strict Clean Architecture layering and a Test-Driven Development approach.
- It provides a sample “Tasks” feature showcasing how presentation, domain, and data layers interact, with dependency injection (get_it) and BLoC/Cubit state management.

##### File structure
- Top-level:
- android/ & ios/ – platform-specific wrappers and build scripts
- lib/ – Dart source code following a feature-first, layered design
- test/ – parallel test suites for each layer and fixtures
- core/ – shared utilities (errors, services, use cases, typedefs)
- Features: Each feature (here “tasks”) contains its own data, domain, and presentation subfolders, enforcing separation of concerns.
- Configuration: pubspec.yaml, analysis_options.yaml, CI workflow (.github/workflows/flutter.yml).

##### README for additional insights
- Confirms use of Clean Architecture, TDD, flutter_bloc (Cubit), get_it, dartz for functional error handling, http client for remote calls, equatable, mocktail, and bloc_test.

##### Detail without over-crowding
- Every layer: Core, Features (Presentation, Domain, Data), External API, Platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Layer
    subgraph "Mobile Platform"
        AndroidShell("Android Shell"):::platform
        iOSShell("iOS Shell"):::platform
    end

    subgraph "Flutter Engine & Dart VM"
        Engine{{"Flutter Engine & Dart VM"}}:::platform
    end

    %% Core Layer
    subgraph "Core"
        ServiceLocator["Service Locator"]:::core
        Exceptions["Exceptions"]:::core
        Failure["Failure Classes"]:::core
        BaseUseCase["Base UseCase Abstraction"]:::core
        Typedefs["Typedefs"]:::core
        Constants["Constants"]:::core
    end

    %% App Entry Point
    Main["main.dart"]:::entry

    %% Features - Tasks
    subgraph "Features - Tasks"
        subgraph "Presentation Layer"
            TasksHome["TasksHome Screen"]:::presentation
            TaskCubit["TasksCubit"]:::presentation
            TaskState["TaskState"]:::presentation
            AddTaskDialog["AddTaskDialog"]:::presentation
            LoadingColumn["LoadingColumn"]:::presentation
            TaskCard["TaskCard"]:::presentation
            TasksListView["TasksListView"]:::presentation
        end

        subgraph "Domain Layer"
            TaskEntity["TaskEntity"]:::domain
            TaskRepositoryInterface["TaskRepository Interface"]:::domain
            CreateTaskUseCase["CreateTaskUseCase"]:::domain
            GetAllTasksUseCase["GetAllTasksUseCase"]:::domain
        end

        subgraph "Data Layer"
            TaskRemoteDataSource["TaskRemoteDataSource"]:::data
            TaskDataSource["TaskDataSource"]:::data
            TaskModel["TaskModel"]:::data
            TaskRepositoryImpl["TaskRepositoryImpl"]:::data
        end
    end

    %% External Services
    ExternalAPI(("External REST API")):::external

    %% Relationships
    AndroidShell --> Engine
    iOSShell --> Engine
    Engine --> Main
    Main -->|"registers dependencies"| ServiceLocator
    ServiceLocator --> TaskCubit
    ServiceLocator --> CreateTaskUseCase
    ServiceLocator --> GetAllTasksUseCase
    ServiceLocator --> TaskRepositoryImpl
    ServiceLocator --> TaskRemoteDataSource

    TasksHome -->|"triggers events"| TaskCubit
    TaskCubit -->|"calls create()"| CreateTaskUseCase
    TaskCubit -->|"calls getAll()"| GetAllTasksUseCase
    CreateTaskUseCase -->|"depends on"| TaskRepositoryInterface
    GetAllTasksUseCase -->|"depends on"| TaskRepositoryInterface

    TaskRepositoryImpl -->|"implements"| TaskRepositoryInterface
    TaskRepositoryImpl -->|"uses"| TaskRemoteDataSource
    TaskRemoteDataSource -->|"fetchAll() → List<TaskModel>"| ExternalAPI
    TaskRemoteDataSource -->|"maps to"| TaskModel
    TaskModel -->|"to Entity"| TaskEntity
    ExternalAPI -.->|"returns JSON"| TaskRemoteDataSource
    TaskCubit -.->|"Either<Failure, List<TaskEntity>>"| TasksHome

    %% Click Events
    click AndroidShell "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/tree/main/android/"
    click iOSShell "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/tree/main/ios/"
    click ServiceLocator "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/services/service_locator.dart"
    click Exceptions "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/errors/exceptions.dart"
    click Failure "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/errors/failure.dart"
    click BaseUseCase "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/usecases/usecase.dart"
    click Typedefs "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/utils/typedef.dart"
    click Constants "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/core/utils/constants.dart"
    click TaskCubit "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/cubits/task/task_cubit.dart"
    click TaskState "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/cubits/task/task_state.dart"
    click TasksHome "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/screens/tasks_home.dart"
    click AddTaskDialog "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/widgets/add_task_dialog.dart"
    click LoadingColumn "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/widgets/loading_column.dart"
    click TaskCard "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/widgets/task_card.dart"
    click TasksListView "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/presentation/widgets/tasks_list_view.dart"
    click TaskEntity "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/domain/entities/task_entity.dart"
    click TaskRepositoryInterface "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/domain/repos/task_repository.dart"
    click CreateTaskUseCase "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/domain/usecases/create_task_use_case.dart"
    click GetAllTasksUseCase "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/domain/usecases/get_all_tasks_use_case.dart"
    click TaskDataSource "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/data/datasources/task_data_source.dart"
    click TaskRemoteDataSource "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/data/datasources/task_remote_data_source.dart"
    click TaskModel "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/data/models/task_model.dart"
    click TaskRepositoryImpl "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/features/tasks/data/repos/task_repository_impl.dart"
    click Main "https://github.com/mahmoudalbndkji/flutter-clean-architecture-tdd-template/blob/main/lib/main.dart"

    %% Styles
    classDef platform fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef entry fill:#d1c4e9,stroke:#333,stroke-width:1px
    classDef core fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef presentation fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef domain fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef data fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#b3e5fc,stroke:#333,stroke-width:1px
```
