# codolingo/mobile architecture

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

- Interactive diagram: https://gitdiagram.com/codolingo/mobile
- Repository: https://github.com/codolingo/mobile

## Overview

##### Project Type and Purpose
- This is a cross-platform Flutter front-end (mobile, web, desktop) for a language-learning app.
- It follows an MVVM pattern with clear separation of UI (widgets), state (ViewModels), domain models, data access (Repositories & Services), and static/dummy data.
- It supports multiple “flavors” (dev, dummy, staging, prod) via different entry points (`main_dev.dart`, `main_dummy.dart`, etc.) and providers (live vs. dummy).

##### File Structure
- Top-level platform folders: `android/`, `ios/`, `linux/`, `macos/`, `windows/`, `web/`.
- Shared UI and logic live under `lib/`:
- `components/` (Atoms → Molecules → Organisms) – widget building blocks
- `pages/` – screen definitions + their ViewModels
- `model/` – API DTOs (`model/api/`), domain classes (`model/class/`), MVVM events & ViewModel base
- `services/api/` – HTTP calls (live & dummy subpackages)
- `repositories/` – orchestrate Services + Transformers
- `transformers/` – convert raw API data → domain models or UI-friendly objects
- `providers/` – configure dependency injection (GetIt) for Dummy vs. Live vs. both
- `main_*.dart` – flavor entrypoints

##### Key Architectural Patterns
- MVVM:
UI Widgets ↔ ViewModels ↔ Repositories ↔ Services ↔ External API or Static JSON
- Dependency Injection: using GetIt
- Flavor-based configuration: different DI bindings for dev/dummy/staging/prod

##### Main Components
A. Platform Host & Flutter Engine
– Android, iOS, macOS, Linux, Windows, Web embed layer
– Flutter Engine
B. Flutter Application
1. Entrypoint (flavor-specific `main_*.dart`)
2. Dependency Injection Container (GetIt)
C. UI Layer
– Atomic widgets (`components/atoms`)
– Composite widgets (`molecules`, `organisms`)
– Screens/Pages (`pages/...View.dart`)
D. MVVM Layer
– ViewModels (`pages/*/*_view_model.dart`)
– MVVM events (`model/mvvm/...`)
E. Domain & Data Layer
– Domain Models (`model/class`)
– API DTOs (`model/api`)
– Transformers (`transformers/`)
– Services (`services/api/live` & `services/api/dummy`)
– Repositories (`repositories/api_repository.dart`, `lesson_repository.dart`)
F. External Systems
– Live Backend API (REST endpoints)
– Static JSON files (dummy provider)

– UI Widget → ViewModel: user actions / data bindings
– ViewModel → Repository: request data
– Repository → Transformer → Domain Model
– Repository → Service → External API or Static JSON → Transformer
– ViewModel ← Repository: emits domain models / updates
– UI ← ViewModel: observes ViewModel streams or events

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Hosts
    subgraph "Platform Hosts"
        A_android["Android"]:::platform
        A_ios["iOS"]:::platform
        A_linux["Linux"]:::platform
        A_macos["macOS"]:::platform
        A_windows["Windows"]:::platform
        A_web["Web"]:::platform
    end
    click A_android "https://github.com/codolingo/mobile/tree/main/codolingo/android/"
    click A_ios "https://github.com/codolingo/mobile/tree/main/codolingo/ios/"
    click A_linux "https://github.com/codolingo/mobile/tree/main/codolingo/linux/"
    click A_macos "https://github.com/codolingo/mobile/tree/main/codolingo/macos/"
    click A_windows "https://github.com/codolingo/mobile/tree/main/codolingo/windows/"
    click A_web "https://github.com/codolingo/mobile/tree/main/codolingo/web/"

    A_android -->|"embed"| FlutterEngine
    A_ios -->|"embed"| FlutterEngine
    A_linux -->|"embed"| FlutterEngine
    A_macos -->|"embed"| FlutterEngine
    A_windows -->|"embed"| FlutterEngine
    A_web -->|"embed"| FlutterEngine

    FlutterEngine["Flutter Engine"]:::platform

    %% Flutter App Entrypoints and DI
    subgraph "Flutter Application"
        subgraph "Entrypoints" 
            E_main["main.dart"]:::entry
            E_dev["main_dev.dart"]:::entry
            E_dummy["main_dummy.dart"]:::entry
            E_staging["main_staging.dart"]:::entry
            E_prod["main_prod.dart"]:::entry
        end
        click E_main "https://github.com/codolingo/mobile/blob/main/codolingo/lib/main.dart"
        click E_dev "https://github.com/codolingo/mobile/blob/main/codolingo/lib/main_dev.dart"
        click E_dummy "https://github.com/codolingo/mobile/blob/main/codolingo/lib/main_dummy.dart"
        click E_staging "https://github.com/codolingo/mobile/blob/main/codolingo/lib/main_staging.dart"
        click E_prod "https://github.com/codolingo/mobile/blob/main/codolingo/lib/main_prod.dart"

        DI["GetIt DI Container"]:::di
        click DI "https://github.com/codolingo/mobile/blob/main/codolingo/lib/providers/provider.dart"
        click DI "https://github.com/codolingo/mobile/blob/main/codolingo/lib/providers/live_provider.dart"
        click DI "https://github.com/codolingo/mobile/blob/main/codolingo/lib/providers/dummy_provider.dart"
    end

    FlutterEngine -->|"launch"| E_main
    FlutterEngine -->|"launch"| E_dev
    FlutterEngine -->|"launch"| E_dummy
    FlutterEngine -->|"launch"| E_staging
    FlutterEngine -->|"launch"| E_prod
    E_main -->|"setup DI"| DI
    E_dev -->|"setup DI"| DI
    E_dummy -->|"setup DI"| DI
    E_staging -->|"setup DI"| DI
    E_prod -->|"setup DI"| DI

    %% UI Layer
    subgraph "UI Layer" 
        Atoms["Atoms"]:::ui
        Molecules["Molecules"]:::ui
        Organisms["Organisms"]:::ui
        subgraph "Pages"
            HomeView["HomePageView"]:::ui
            HomeVM["HomeViewModel"]:::mvvm
            LoginView["LoginPageView"]:::ui
            LoginVM["LoginViewModel"]:::mvvm
            WelcomeView["WelcomePageView"]:::ui
            WelcomeVM["WelcomeViewModel"]:::mvvm
            MapView["MapPageView"]:::ui
            MapVM["MapViewModel"]:::mvvm
            LessonView["LessonPageView"]:::ui
            LessonVM["LessonViewModel"]:::mvvm
        end
    end
    click Atoms "https://github.com/codolingo/mobile/tree/main/codolingo/lib/components/atoms/"
    click Molecules "https://github.com/codolingo/mobile/tree/main/codolingo/lib/components/molecules/"
    click Organisms "https://github.com/codolingo/mobile/tree/main/codolingo/lib/components/organisms/"
    click HomeView "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/home/home_view.dart"
    click HomeVM "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/home/home_view_model.dart"
    click LoginView "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/login/login_view.dart"
    click LoginVM "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/login/login_view_model.dart"
    click WelcomeView "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/welcome/welcome_view.dart"
    click WelcomeVM "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/welcome/welcome_view_model.dart"
    click MapView "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/map/map_view.dart"
    click MapVM "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/map/map_view_model.dart"
    click LessonView "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/lesson/lesson_view.dart"
    click LessonVM "https://github.com/codolingo/mobile/blob/main/codolingo/lib/pages/lesson/lesson_view_model.dart"

    DI -->|"provides VM"| HomeVM
    DI -->|"provides VM"| LoginVM
    DI -->|"provides VM"| WelcomeVM
    DI -->|"provides VM"| MapVM
    DI -->|"provides VM"| LessonVM

    HomeView -->|"binds to"| HomeVM
    LoginView -->|"binds to"| LoginVM
    WelcomeView -->|"binds to"| WelcomeVM
    MapView -->|"binds to"| MapVM
    LessonView -->|"binds to"| LessonVM

    %% MVVM Events & Base
    subgraph "MVVM Core"
        VMBase["ViewModel Base"]:::mvvm
        VMEvent["View Events"]:::mvvm
    end
    click VMBase "https://github.com/codolingo/mobile/blob/main/codolingo/lib/model/mvvm/view_model.dart"
    click VMEvent "https://github.com/codolingo/mobile/blob/main/codolingo/lib/model/mvvm/view_event.dart"
    click VMEvent "https://github.com/codolingo/mobile/tree/main/codolingo/lib/model/mvvm/view_events/"

    HomeVM -->|"extends"| VMBase
    LoginVM -->|"extends"| VMBase
    WelcomeVM -->|"extends"| VMBase
    MapVM -->|"extends"| VMBase
    LessonVM -->|"extends"| VMBase

    %% Domain & Data Layer
    subgraph "Domain & Data"
        DClasses["Domain Models"]:::data
        DTOs["API DTOs"]:::data
        subgraph "Transformers"
            TDomain["Class Transformers"]:::data
            TUI["UI Transformers"]:::data
            TEx["Transformer Exceptions"]:::data
        end
        subgraph "Services"
            LiveService["LiveApiService"]:::data
            DummyService["DummyApiService"]:::data
            APIService["ApiService Interface"]:::data
        end
        subgraph "Repositories"
            APIRepo["ApiRepository"]:::data
            LessonRepo["LessonRepository"]:::data
        end
    end
    click DClasses "https://github.com/codolingo/mobile/tree/main/codolingo/lib/model/class/"
    click DTOs "https://github.com/codolingo/mobile/tree/main/codolingo/lib/model/api/"
    click TDomain "https://github.com/codolingo/mobile/tree/main/codolingo/lib/transformers/class/"
    click TUI "https://github.com/codolingo/mobile/tree/main/codolingo/lib/transformers/ui/"
    click TEx "https://github.com/codolingo/mobile/blob/main/codolingo/lib/transformers/transformer_exception.dart"
    click LiveService "https://github.com/codolingo/mobile/blob/main/codolingo/lib/services/api/live/live_api_service.dart"
    click DummyService "https://github.com/codolingo/mobile/blob/main/codolingo/lib/services/api/dummy/dummy_api_service.dart"
    click APIService "https://github.com/codolingo/mobile/blob/main/codolingo/lib/services/api/api_service.dart"
    click APIRepo "https://github.com/codolingo/mobile/blob/main/codolingo/lib/repositories/api/api_repository.dart"
    click LessonRepo "https://github.com/codolingo/mobile/blob/main/codolingo/lib/repositories/lesson_repository.dart"

    HomeVM -->|"calls"| APIRepo
    LoginVM -->|"calls"| APIRepo
    WelcomeVM -->|"calls"| APIRepo
    MapVM -->|"calls"| APIRepo
    LessonVM -->|"calls"| LessonRepo

    APIRepo -->|"uses"| APIService
    LessonRepo -->|"uses"| APIService
    APIRepo -->|"uses"| TDomain
    APIRepo -->|"uses"| TUI
    LessonRepo -->|"uses"| TDomain
    LessonRepo -->|"uses"| TUI

    APIService -->|"live call"| LiveService
    APIService -->|"dummy call"| DummyService

    LiveService -->|"HTTP"| ExternalAPI
    DummyService -->|"reads"| StaticJSON
    TDomain -->|"transforms"| DClasses
    TUI -->|"transforms"| DTOs

    %% External Systems
    subgraph "External Systems"
        ExternalAPI["Backend API"]:::external
        StaticJSON["Static JSON Files"]:::external
    end
    click StaticJSON "https://github.com/codolingo/mobile/tree/main/codolingo/static/dummy/api/"

    ExternalAPI -->|"response"| LiveService
    StaticJSON -->|"response"| DummyService

    %% Styling
    classDef platform fill:#d3d3d3,stroke:#555,stroke-width:1px
    classDef engine fill:#bbbbbb,stroke:#555,stroke-width:1px
    classDef entry fill:#cba6f7,stroke:#555,stroke-width:1px
    classDef di fill:#f9e2af,stroke:#555,stroke-width:1px
    classDef ui fill:#89b4fa,stroke:#555,stroke-width:1px
    classDef mvvm fill:#a6e3a1,stroke:#555,stroke-width:1px
    classDef data fill:#fab387,stroke:#555,stroke-width:1px
    classDef external fill:#b4befe,stroke:#555,stroke-width:1px
```
