# phongwild/nettromdex architecture

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

- Interactive diagram: https://gitdiagram.com/phongwild/nettromdex
- Repository: https://github.com/phongwild/nettromdex

## Overview

##### Main Components
- Frontend (User Interface):
- Flutter UI elements including: screens (found under lib/feature/screens), widgets (lib/feature/widgets and lib/core_ui), and design system components.
- Navigation and routing: Managed by the router modules (lib/feature/router and lib/global/router).
- State management: Implemented via Cubits (in lib/feature/cubit) that maintain UI state (auth, manga listings, detail pages, etc.).
- Domain/Business Logic Layer:
- Use cases (lib/domain/usecase) that encapsulate business rules (for example, account authentication and manga retrieval).
- Domain repositories (lib/domain/repository) which define interfaces to be implemented in the data layer.
- Environment configuration (lib/domain/env_config) for handling API endpoints and different URL types.
- Data/Repository Layer:
- Model definitions and request/response handling, based in lib/data/models and lib/data/request.
- Repository implementations (lib/data/repository) that communicate with remote services.
- Network/External Integration:
- REST client and networking modules (lib/core/networking) that integrate with MangaDex API.
- Usage of interceptors (logger, retry, session management, error handling) to manage HTTP requests.
- Socket communications (lib/core/socket) for real-time features such as updating chapters.
- Core Services & Utilities:
- Caching and local storage (lib/core/cache, with secure storage and shared preferences).
- Analytics and tracking (lib/core/analytics) including integration with Firebase.
- Dependency injection and initialization (lib/global/init_app) that structure how various parts of the application are wired together.
- Global configurations such as internationalization (l10n files, lib/global/l10n) and theming (lib/core_ui/app_theme).

##### Relationships and Interactions
- The UI (presentation layer) interacts with Cubits/blocs, which in turn call the domain use cases.
- Use cases invoke repository functions; repositories abstract the data sources (network API calls or local caches).
- The networking layer handles HTTP requests with configurable interceptors to manage common error handling, session management, and logging.
- Analytics and socket connection modules run in parallel to capture user events and real-time updates.
- All dependencies are managed via the dependency injector (lib/global/init_app/injector* files) to provide controllable service construction and mocking for testing.

##### Highlighting Architectural Patterns and Design Principles
- Layered/Clean Architecture: Present a clear separation between presentation, domain, and data layers. This improves maintainability and testability.
- Dependency Injection: Used for wiring together services and managers.
- Repository Pattern: Abstracts data sources (remote MangaDex API and local caches) behind well-defined interfaces.
- State Management: Implemented using Cubit (or a similar pattern) for managing UI state in reaction to data changes.
- Multi-platform Configuration: Note that the project contains directories for Android, iOS, Linux, macOS, Windows, and Web, highlighting Flutter’s cross-platform nature.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "UI / Presentation Layer"
        UI_Screens["Screens"]:::frontend
        UI_Widgets["Widgets (Feature)"]:::frontend
        UI_CoreUI["Core UI Components"]:::frontend
        UI_Router["Navigation & Routing (Feature)"]:::frontend
        UI_GlobalRouter["Navigation & Routing (Global)"]:::frontend
    end

    subgraph "State Management Layer"
        Cubits["State Management (Cubits)"]:::state
    end

    subgraph "Domain / Business Logic Layer"
        UseCases["Use Cases"]:::domain
        RepoInterfaces["Repository Interfaces"]:::domain
        EnvConfig["Environment Config"]:::domain
    end

    subgraph "Data / Repository Layer"
        DataModels["Data Models"]:::data
        RequestHandling["Request/Response Handling"]:::data
        RepoImpl["Repository Implementations"]:::data
    end

    subgraph "Network / External Integration Layer"
        RestClient["REST Client & Networking"]:::network
        Interceptors["Interceptors"]:::network
        SocketComm["Socket Communications"]:::network
    end

    subgraph "Core Services & Utilities"
        Cache["Caching & Local Storage"]:::core
        Analytics["Analytics & Tracking"]:::core
        DI["Dependency Injection & Initialization"]:::core
        Intl["Internationalization"]:::core
        Theming["Theming"]:::core
    end

    subgraph "External Services"
        MangaDexAPI["MangaDex API"]:::external
        Firebase["Firebase Analytics"]:::external
        RealTimeSocket["Real-Time Socket Services"]:::external
    end

    %% UI Layer interactions
    UI_Screens -->|"update"| Cubits
    UI_Widgets -->|"update"| Cubits
    UI_CoreUI -->|"display"| Cubits
    UI_Router -->|"navigate"| Cubits
    UI_GlobalRouter -->|"navigate"| Cubits
    UI_GlobalRouter -->|"routeTo"| UI_Screens

    %% State Management to Domain
    Cubits -->|"trigger"| UseCases

    %% Domain Layer interactions
    UseCases -->|"access"| RepoInterfaces
    UseCases -->|"useConfig"| EnvConfig
    RepoInterfaces -->|"implementedBy"| RepoImpl

    %% Data Layer interactions
    DataModels -->|"provideModel"| RepoImpl
    RequestHandling -->|"handleReqRes"| RepoImpl

    %% Data to Network & Core Layer
    RepoImpl -->|"fetchSubmit"| RestClient
    RepoImpl -->|"cacheLookup"| Cache

    %% Network Layer interactions
    RestClient -->|"HTTP_Request"| MangaDexAPI
    RestClient -->|"useInterceptors"| Interceptors
    SocketComm -->|"realTimeUpdate"| RealTimeSocket

    %% Core Services interactions
    Analytics -->|"reportTo"| Firebase
    DI --- Cubits
    DI --- UseCases
    DI --- RepoImpl
    DI --- RestClient
    Intl -->|"provideLanguage"| UI_CoreUI
    Theming -->|"applyTheme"| UI_CoreUI

    %% Click Events
    click UI_Screens "https://github.com/phongwild/nettromdex/tree/main/lib/feature/screens"
    click UI_Widgets "https://github.com/phongwild/nettromdex/tree/main/lib/feature/widgets"
    click UI_CoreUI "https://github.com/phongwild/nettromdex/tree/main/lib/core_ui"
    click UI_Router "https://github.com/phongwild/nettromdex/tree/main/lib/feature/router"
    click UI_GlobalRouter "https://github.com/phongwild/nettromdex/tree/main/lib/global/router"
    click Cubits "https://github.com/phongwild/nettromdex/tree/main/lib/feature/cubit"
    click UseCases "https://github.com/phongwild/nettromdex/tree/main/lib/domain/usecase"
    click RepoInterfaces "https://github.com/phongwild/nettromdex/tree/main/lib/domain/repository"
    click EnvConfig "https://github.com/phongwild/nettromdex/tree/main/lib/domain/env_config"
    click DataModels "https://github.com/phongwild/nettromdex/tree/main/lib/data/models"
    click RequestHandling "https://github.com/phongwild/nettromdex/tree/main/lib/data/request"
    click RepoImpl "https://github.com/phongwild/nettromdex/tree/main/lib/data/repository"
    click RestClient "https://github.com/phongwild/nettromdex/tree/main/lib/core/networking"
    click Interceptors "https://github.com/phongwild/nettromdex/tree/main/lib/core/networking/interceptor"
    click SocketComm "https://github.com/phongwild/nettromdex/tree/main/lib/core/socket"
    click Cache "https://github.com/phongwild/nettromdex/tree/main/lib/core/cache"
    click Analytics "https://github.com/phongwild/nettromdex/tree/main/lib/core/analytics"
    click DI "https://github.com/phongwild/nettromdex/tree/main/lib/global/init_app"
    click Intl "https://github.com/phongwild/nettromdex/tree/main/lib/global/l10n"
    click Theming "https://github.com/phongwild/nettromdex/tree/main/lib/core_ui/app_theme"

    %% Styles
    classDef frontend fill:#ffdddd,stroke:#d42,stroke-width:2px;
    classDef state fill:#ddffdd,stroke:#2d2,stroke-width:2px;
    classDef domain fill:#ddddff,stroke:#22d,stroke-width:2px;
    classDef data fill:#ffffdd,stroke:#dd2,stroke-width:2px;
    classDef network fill:#ddffff,stroke:#2dd,stroke-width:2px;
    classDef core fill:#ffeedd,stroke:#d8a,stroke-width:2px;
    classDef external fill:#e6e6fa,stroke:#888,stroke-width:2px;
```
