# codeabelity/neuma-base-flutter architecture

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

- Interactive diagram: https://gitdiagram.com/codeabelity/neuma-base-flutter
- Repository: https://github.com/codeabelity/neuma-base-flutter

## Overview

##### Project type and purpose
- This is a Flutter mobile-app starter (“Neuma Base Flutter”) with a feature-first, DDD-inspired layered architecture.
- Goal: Rapid prototyping and scalable, production-ready code across multiple features.

##### File structure
- core/
- services/ (navigation, logging, etc.)
- theme/ (app theme data)
- utils/ (helper functions)
- data/
- api/ (HTTP clients, endpoints)
- database/ (local DB interfaces)
- models/ (DTOs, data representations)
- repositories/ (concrete data-source implementations)
- features/
- home/ and profile/ modules, each with:
– domain/ (entities, use-cases, abstract repos)
– presentation/ (screens, widgets)
– state/ (Bloc/Cubit or Provider state classes)
- routing/ (app routing configuration)
- shared/
- dialogs/, extensions/, widgets/ (reusable UI & logic)
- main.dart (entry point)
- test/ mirrors the same structure for unit/widget tests

##### README for additional insights
- Confirms DDD-inspired, feature-first separation
- Highlights use of Dart/Flutter, no separate backend—app calls remote APIs and local DB
- Core and shared modules supply cross-cutting concerns

a. Main components:
- Presentation layer (features/…/presentation)
- State management (features/…/state)
- Domain layer (features/…/domain)
- Data layer (data/repos, models, api, database)
- Core services (core/services)
- Shared UI & logic (shared/)
- Routing engine (routing/)
- External services: Remote API, Local DB
- Entry: main.dart → routing
b. Relationships & interactions:
1. User interacts with Presentation widgets
2. Widgets dispatch events to State managers
3. State managers invoke Domain use cases
4. Use cases call Repository interfaces
5. Repositories delegate to API clients or DB interfaces
6. Core services (navigation, logging) are injected into Presentation and Data layers
7. Shared widgets/dialogs are imported by Presentation
c. Architectural patterns & principles:
- Layered architecture (Presentation → Domain → Data → External)
- Feature isolation (each feature encapsulates its own layers)
- Dependency Inversion: Domain depends on abstract repos, concrete repos live in Data
- Separation of concerns: Core vs. Shared vs. Feature vs. Data
d. Key technologies:
- Dart & Flutter SDK
- State management (Bloc/Cubit or Provider)
- HTTP client (lib/data/api)
- Local DB (SQLite via lib/data/database)
- Theming (core/theme) and constants (core/constants)
- Navigation (routing/my_routing.dart and core/services)

##### Detail without clutter
- Folder as a sub-component in its layer.
- Main.dart at the top, feeding into Routing.

## Diagram (Mermaid)

```mermaid
graph TB
    main["main.dart"]:::entry --> routing["Routing Engine"]:::routing

    subgraph "Presentation & State" 
        direction TB
        subgraph "Home Feature"
            HP["HomePresentation"]:::presentation
            HS["HomeState"]:::state
        end
        subgraph "Profile Feature"
            PP["ProfilePresentation"]:::presentation
            PS["ProfileState"]:::state
        end
    end

    routing --> HP
    routing --> PP

    HP --> HS
    PP --> PS

    subgraph "Domain Layer"
        direction TB
        HD["HomeDomain"]:::domain
        PD["ProfileDomain"]:::domain
    end

    HS --> HD
    PS --> PD

    subgraph "Data Layer"
        direction TB
        Repo["UserRepositoryImpl"]:::data
        API["API Client"]:::data
        DB["Database Interface"]:::data
        Model["Data Models"]:::data
    end

    HD --> Repo
    PD --> Repo
    Repo --> API
    Repo --> DB
    API --> Model
    DB --> Model

    subgraph "Core Modules"
        direction TB
        CS["Core Services"]:::core
        CC["Core Constants"]:::core
        CT["Core Theme"]:::core
        CU["Core Utilities"]:::core
    end

    CS -.-> HP
    CS -.-> HS
    CS -.-> Repo
    CC -.-> CT
    CU -.-> HP

    subgraph "Shared Modules"
        direction TB
        SD["Shared Dialogs"]:::shared
        SE["Shared Extensions"]:::shared
        SW["Shared Widgets"]:::shared
    end

    SD --> HP
    SW --> PP

    subgraph "External Services"
        direction TB
        ExtAPI["Remote API"]:::external
        ExtDB["Local DB"]:::external
    end

    API --> ExtAPI
    DB --> ExtDB

    %% Click Events
    click main "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/main.dart"
    click routing "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/routing/my_routing.dart"
    click CS "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/core/services/my_service.dart"
    click CC "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/core/constants/my_constant.dart"
    click CT "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/core/theme/my_theme.dart"
    click CU "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/core/utils/my_utils.dart"
    click API "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/data/api/my_api.dart"
    click DB "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/data/database/my_database.dart"
    click Model "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/data/models/my_model.dart"
    click Repo "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/data/repositories/my_repository.dart"
    click HD "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/home/domain/my_domain.dart"
    click HS "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/home/state/my_state.dart"
    click HP "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/home/presentation/my_presentation.dart"
    click PD "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/profile/domain/my_domain.dart"
    click PS "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/profile/state/my_state.dart"
    click PP "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/features/profile/presentation/my_presentation.dart"
    click SD "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/shared/dialogs/my_dialog.dart"
    click SE "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/shared/extensions/my_extension.dart"
    click SW "https://github.com/codeabelity/neuma-base-flutter/blob/main/lib/shared/widgets/my_widget.dart"

    %% Styles
    classDef entry fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef routing fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef presentation fill:#add8e6,stroke:#333
    classDef state fill:#add8e6,stroke:#333
    classDef domain fill:#90ee90,stroke:#333
    classDef data fill:#ffa500,stroke:#333
    classDef core fill:#d3d3d3,stroke:#333,stroke-dasharray: 5 5
    classDef shared fill:#dda0dd,stroke:#333
    classDef external fill:#ffcccb,stroke:#333,stroke-width:2px style external stroke-dasharray: 2 2
```
