# vborbely/todo_sample architecture

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

- Interactive diagram: https://gitdiagram.com/vborbely/todo_sample
- Repository: https://github.com/vborbely/todo_sample

## Overview

##### Overall Project Type and Purpose
- This is a Flutter-based ToDo application sample, aimed at demonstrating basic state management (using bloc), local & secure storage (using hive and flutter_secure_storage), and routing (via go_router).
- The project supports multiple platforms: Web, Android, iOS, macOS, Linux, and Windows.

##### Main Architectural Components
– Entry Point & App Bootstrap:
- lib/main.dart initializes the Flutter application.
- Environment configuration is set via the environment files (env.dev, env.mock, env.production, env.staging, env.template).

– Application Layer (Application Domain):
- Located in lib/application (with subdirectories for config, errors, and utils).
- Handles global configuration constants, environment configurations, and logging.

– Data Layer:
- Contains subdirectories for cubits (state management using bloc), entities (data models along with Hive adaptations), repositories (data access abstraction), and services (e.g., storage service).
- This layer defines how data is processed, stored (Hive, secure storage), and provided to the rest of the application.

– Presentation Layer:
- Resides in lib/presentation and is further subdivided into screens like home, person, settings as well as shared widgets.
- Manages user interface components and interactions.

– External and Third-Party Libraries:
- bloc – for state management.
- flutter_secure_storage – for secure data storage.
- hive – for local persistence of entities.
- go_router – for handling navigation and routing.

##### Interactions & Data Flow
– The Flutter entry (main.dart) loads configurations from the Application layer.
– The Presentation layer (UI screens and widgets) communicates with state management controllers (cubits) in the Data layer.
– Cubits manage state changes and use repositories to fetch or persist data (using Hive over secure storage).
– Repositories encapsulate interactions with services (like the storage service) and data entities.
– Routing is managed by configuration from the Application layer (as seen in router.dart) using go_router.

##### Important Architectural Patterns
– Layered Architecture: Clear separation between presentation, application, and data management.
– State management using the BLoC pattern (cubits).
– Repository Pattern for abstracting data sources.
– Use of environment-based configurations, emphasizing flexibility across different platforms and build modes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    EntryPoint["Entry Point: main.dart"]:::flutter

    %% Environment Configurations
    subgraph "Environment Configurations"
        EDev["Env Dev"]:::config
        EMock["Env Mock"]:::config
        EProd["Env Production"]:::config
        EStag["Env Staging"]:::config
        ETempl["Env Template"]:::config
    end

    %% Application Layer
    subgraph "Application Layer"
        AppMain["App Main"]:::flutter
        Config["Configuration (config)"]:::flutter
        Errors["Errors"]:::flutter
        Utils["Utils"]:::flutter
    end

    %% Data Layer
    subgraph "Data Layer"
        Cubits["Cubits (State Management)"]:::flutter
        Entities["Entities (Data Models)"]:::flutter
        Repositories["Repositories"]:::flutter
        Services["Services (Storage)"]:::flutter
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        PresentationCore["Presentation Core"]:::flutter
        HomeScreen["Home Screen"]:::flutter
        PersonScreen["Person Screen"]:::flutter
        SettingsScreen["Settings Screen"]:::flutter
        TodoScreen["Todo Screen"]:::flutter
        Widgets["Widgets"]:::flutter
        Theme["Theme"]:::flutter
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Bloc["bloc"]:::external
        FlutterSecure["flutter_secure_storage"]:::external
        Hive["hive"]:::external
        GoRouter["go_router"]:::external
    end

    %% Connections from Entry & Environment to Application Layer
    EntryPoint --> AppMain
    EDev --> AppMain
    EMock --> AppMain
    EProd --> AppMain
    EStag --> AppMain
    ETempl --> AppMain

    %% Application Layer internal flow
    AppMain --> Config
    AppMain --> Errors
    AppMain --> Utils
    AppMain --> PresentationCore

    %% Configuration to External Routing
    Config -->|"uses"| GoRouter

    %% Presentation Layer setup
    PresentationCore --> HomeScreen
    PresentationCore --> PersonScreen
    PresentationCore --> SettingsScreen
    PresentationCore --> TodoScreen
    PresentationCore --> Theme

    HomeScreen --> Widgets
    PersonScreen --> Widgets
    SettingsScreen --> Widgets
    TodoScreen --> Widgets

    %% Presentation to Data flow
    HomeScreen -->|"triggers"| Cubits
    PersonScreen -->|"triggers"| Cubits
    SettingsScreen -->|"triggers"| Cubits
    TodoScreen -->|"triggers"| Cubits

    %% Data Layer internal flow
    Cubits --> Repositories
    Repositories --> Entities
    Repositories --> Services

    %% Data Layer External Dependencies
    Cubits -->|"implemented_by"| Bloc
    Services -->|"uses"| FlutterSecure
    Entities -->|"persisted_in"| Hive

    %% Styles
    classDef flutter fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef external fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;

    %% Click Events
    click EntryPoint "https://github.com/vborbely/todo_sample/blob/master/lib/main.dart"
    click EDev "https://github.com/vborbely/todo_sample/blob/master/env.dev"
    click EMock "https://github.com/vborbely/todo_sample/blob/master/env.mock"
    click EProd "https://github.com/vborbely/todo_sample/blob/master/env.production"
    click EStag "https://github.com/vborbely/todo_sample/blob/master/env.staging"
    click ETempl "https://github.com/vborbely/todo_sample/blob/master/env.template"
    click AppMain "https://github.com/vborbely/todo_sample/blob/master/lib/application/app_main.dart"
    click Config "https://github.com/vborbely/todo_sample/tree/master/lib/application/config"
    click Errors "https://github.com/vborbely/todo_sample/blob/master/lib/application/errors/error.dart"
    click Utils "https://github.com/vborbely/todo_sample/blob/master/lib/application/utils/logger.dart"
    click Cubits "https://github.com/vborbely/todo_sample/tree/master/lib/data/cubits"
    click Entities "https://github.com/vborbely/todo_sample/tree/master/lib/data/entities"
    click Repositories "https://github.com/vborbely/todo_sample/tree/master/lib/data/repositories"
    click Services "https://github.com/vborbely/todo_sample/blob/master/lib/data/services/storage_service.dart"
    click HomeScreen "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/home/home_screen.dart"
    click PersonScreen "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/person/person_details_screen.dart"
    click SettingsScreen "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/settings/settings_screen.dart"
    click TodoScreen "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/todo/todo_details_screen.dart"
    click Widgets "https://github.com/vborbely/todo_sample/tree/master/lib/presentation/widgets"
    click PresentationCore "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/presentation.dart"
    click Theme "https://github.com/vborbely/todo_sample/blob/master/lib/presentation/theme.dart"
```
