# kimmich4/mobile_frontend architecture

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

- Interactive diagram: https://gitdiagram.com/kimmich4/mobile_frontend
- Repository: https://github.com/kimmich4/mobile_frontend

## Overview

1. **Overall shape**
   - This repository is a **Flutter cross-platform client** plus a **Node.js backend** that appears to power AI-assisted fitness features. The Flutter app targets Android, iOS, web, macOS, Linux, and Windows from one codebase.

2. **Client-side architecture**
   - The Flutter app is organized around a fairly strict layering:
     - `ui/` for screens, widgets, and reusable components
     - `viewmodels/` for screen state and user actions
     - `data/` for repositories, models, and network services
     - `core/` for cross-cutting concerns like theming
   - This suggests a presentation → state → data boundary rather than direct service calls from UI.

3. **Navigation and app entry**
   - `lib/main.dart` is the app entry point.
   - The screen set includes onboarding, auth, profile setup, home, main shell navigation, workout, diet, progress tracking, settings, AI assistant, video, and splash screens.
   - `main_screen.dart` likely acts as the primary post-login container that coordinates major sections of the app.

4. **Domain modules in the Flutter app**
   - The domain is fitness/wellness oriented, with models for:
     - users
     - workouts
     - diets
     - progress
     - chat/messages
   - Each domain has both a repository and, in many cases, a view model, indicating the app likely keeps business logic out of the UI layer.

5. **Data access boundary**
   - `lib/data/services/api_service.dart` is the central network abstraction for the Flutter app.
   - Repositories such as `auth_repository.dart`, `workout_repository.dart`, `diet_repository.dart`, `progress_repository.dart`, and `user_repository.dart` likely wrap `ApiService` and expose feature-specific operations to view models.
   - `firebase_options.dart` indicates Firebase is configured in the Flutter client, though the exact service usage is not visible from the tree alone.

6. **State management pattern**
   - The presence of `base_view_model.dart` and one view model per feature strongly suggests a shared state-management base class with feature-specific subclasses.
   - This creates a clean flow: **UI screen → view model → repository → API/service → backend**.

7. **AI assistant subsystem**
   - The AI assistant is a distinct vertical slice in both client and backend:
     - Flutter: `ai_assistant_screen.dart` and `ai_assistant_view_model.dart`
     - Backend: `ai_assistant.js`, `rag_chain.js`, `rag_logic.js`
   - This indicates chat-like interaction on the client, with backend orchestration for retrieval-augmented generation rather than the UI talking directly to an LLM provider.

8. **Backend responsibilities**
   - The Node backend is not just a simple API wrapper; it contains specialized modules for:
     - AI assistant handling
     - OCR logic
     - plan generation
     - retrieval / RAG orchestration
     - fallback behavior
   - `index.js` is the backend entry point, with the other files acting as feature modules.

9. **Retrieval and vector search**
   - `qdrant_client.js` implies the backend integrates with **Qdrant** as a vector database or similarity search layer.
   - Combined with `rag_chain.js` and `rag_logic.js`, the architecture likely follows:
     - user query or document input
     - retrieval from Qdrant
     - prompt/chain assembly
     - generated response returned to the Flutter client

10. **OCR and document/vision path**
    - `ocr_logic.js` indicates an OCR pipeline exists in the backend.
    - This likely feeds extracted text into the AI/planning flow, enabling image-to-text or scan-based ingestion for the assistant or workout/diet features.

11. **Plan generation**
    - `plan_generator.js` suggests backend generation of structured plans, probably workout or diet plans, possibly using retrieved context and/or AI output.
    - This is a separate concern from general chat, implying the backend has both conversational and structured recommendation workflows.

12. **Fallback and resiliency**
    - `fallbacks.js` shows the backend has explicit non-primary paths when AI, retrieval, or extraction fails.
    - That suggests the system is designed to degrade gracefully instead of failing hard when external services or model calls are unavailable.

13. **Testing layout**
    - There is substantial automated test coverage on both sides:
      - Flutter unit tests under `test/` for models, repositories, services, and view models
      - Backend tests under `backend/testing/`
    - This mirrors the architecture layers and helps validate each subsystem independently.

14. **Platform packaging**
    - The repo includes standard Flutter platform shells for Android, iOS, web, macOS, Linux, and Windows.
    - These platform folders are mostly host wrappers; the real application logic lives in `lib/` and the backend service code.

15. **What an architecture diagram should emphasize**
    - The main diagram should show:
      - a Flutter client with layered UI/viewmodel/repository/service structure
      - a Node backend providing AI, OCR, planning, and RAG features
      - Qdrant as the retrieval/vector store
      - Firebase configuration present in the client
      - clear boundaries between presentation, client data access, backend orchestration, and external AI/search dependencies

Main entry points: [`lib/main.dart`](https://github.com/kimmich4/mobile_frontend/blob/main/lib/main.dart) (App entry), [`backend/testing`](https://github.com/kimmich4/mobile_frontend/tree/main/backend/testing) (Backend tests), [`lib/ui`](https://github.com/kimmich4/mobile_frontend/tree/main/lib/ui) (UI screens), [`backend/index.js`](https://github.com/kimmich4/mobile_frontend/blob/main/backend/index.js) (Backend entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_lib_main["App entry<br/>Flutter entry<br/>[main.dart]"]
  node_ui_shell["UI screens<br/>Presentation layer"]
  node_viewmodels["View models<br/>State layer"]
  node_data_layer["Data layer<br/>Repositories and services"]
  node_api_service["API service<br/>HTTP gateway<br/>[api_service.dart]"]
  node_repos["Repos"]
  node_models["Domain models<br/>Data models"]
  node_theme["Theme<br/>UI core<br/>[theme_manager.dart]"]
  node_firebase["Firebase config<br/>Client config"]
end

subgraph group_backend["Node backend"]
  node_backend_entry["Backend entry<br/>Node entry<br/>[index.js]"]
  node_ai_assistant["AI assistant<br/>Backend feature<br/>[ai_assistant.js]"]
  node_rag_chain["RAG chain<br/>Retrieval pipeline<br/>[rag_chain.js]"]
  node_rag_logic["RAG logic<br/>Retrieval logic<br/>[rag_logic.js]"]
  node_qdrant["Qdrant client<br/>Vector search<br/>[qdrant_client.js]"]
  node_ocr["OCR logic<br/>Text extraction<br/>[ocr_logic.js]"]
  node_plans["Plan generator<br/>Structured generation<br/>[plan_generator.js]"]
  node_fallbacks["Fallbacks<br/>Resilience layer<br/>[fallbacks.js]"]
end

subgraph group_platforms["Platform shells"]
  node_android_shell["Android<br/>Platform host<br/>[MainActivity.kt]"]
  node_ios_shell["iOS<br/>Platform host<br/>[AppDelegate.swift]"]
  node_desktop_shell["Desktop<br/>Platform host<br/>[main.cc]"]
  node_web_shell["Web<br/>Platform host<br/>[index.html]"]
end

subgraph group_tests["Tests"]
  node_client_tests["Client tests<br/>Flutter tests"]
  node_backend_tests["Backend tests<br/>Node tests"]
end

node_lib_main -->|"boots"| node_ui_shell
node_ui_shell -->|"binds"| node_viewmodels
node_viewmodels -->|"uses"| node_repos
node_repos -->|"calls"| node_api_service
node_repos -->|"maps"| node_models
node_viewmodels -->|"consumes"| node_models
node_ui_shell -->|"styles"| node_theme
node_lib_main -.->|"configures"| node_firebase
node_backend_entry -->|"routes"| node_ai_assistant
node_backend_entry -->|"routes"| node_plans
node_backend_entry -->|"routes"| node_ocr
node_ai_assistant -->|"uses"| node_rag_chain
node_rag_chain -->|"coordinates"| node_rag_logic
node_rag_chain -->|"retrieves"| node_qdrant
node_ocr -.->|"feeds"| node_rag_logic
node_plans -.->|"uses"| node_rag_logic
node_fallbacks -.->|"backs up"| node_ai_assistant
node_fallbacks -.->|"backs up"| node_ocr
node_fallbacks -.->|"backs up"| node_plans
node_ui_shell -.->|"calls"| node_backend_entry
node_android_shell -.->|"hosts"| node_lib_main
node_ios_shell -.->|"hosts"| node_lib_main
node_desktop_shell -.->|"hosts"| node_lib_main
node_web_shell -.->|"hosts"| node_lib_main
node_client_tests -.->|"covers"| node_viewmodels
node_client_tests -.->|"covers"| node_repos
node_client_tests -.->|"covers"| node_api_service
node_backend_tests -.->|"covers"| node_ai_assistant
node_backend_tests -.->|"covers"| node_rag_chain
node_backend_tests -.->|"covers"| node_qdrant
node_backend_tests -.->|"covers"| node_ocr
node_backend_tests -.->|"covers"| node_plans

click node_lib_main "https://github.com/kimmich4/mobile_frontend/blob/main/lib/main.dart"
click node_ui_shell "https://github.com/kimmich4/mobile_frontend/tree/main/lib/ui"
click node_viewmodels "https://github.com/kimmich4/mobile_frontend/tree/main/lib/viewmodels"
click node_data_layer "https://github.com/kimmich4/mobile_frontend/tree/main/lib/data"
click node_api_service "https://github.com/kimmich4/mobile_frontend/blob/main/lib/data/services/api_service.dart"
click node_repos "https://github.com/kimmich4/mobile_frontend/tree/main/lib/data/repositories"
click node_models "https://github.com/kimmich4/mobile_frontend/tree/main/lib/data/models"
click node_theme "https://github.com/kimmich4/mobile_frontend/blob/main/lib/core/theme/theme_manager.dart"
click node_firebase "https://github.com/kimmich4/mobile_frontend/blob/main/lib/firebase_options.dart"
click node_backend_entry "https://github.com/kimmich4/mobile_frontend/blob/main/backend/index.js"
click node_ai_assistant "https://github.com/kimmich4/mobile_frontend/blob/main/backend/ai_assistant.js"
click node_rag_chain "https://github.com/kimmich4/mobile_frontend/blob/main/backend/rag_chain.js"
click node_rag_logic "https://github.com/kimmich4/mobile_frontend/blob/main/backend/rag_logic.js"
click node_qdrant "https://github.com/kimmich4/mobile_frontend/blob/main/backend/qdrant_client.js"
click node_ocr "https://github.com/kimmich4/mobile_frontend/blob/main/backend/ocr_logic.js"
click node_plans "https://github.com/kimmich4/mobile_frontend/blob/main/backend/plan_generator.js"
click node_fallbacks "https://github.com/kimmich4/mobile_frontend/blob/main/backend/fallbacks.js"
click node_android_shell "https://github.com/kimmich4/mobile_frontend/blob/main/android/app/src/main/kotlin/com/example/mobile_frontend/MainActivity.kt"
click node_ios_shell "https://github.com/kimmich4/mobile_frontend/blob/main/ios/Runner/AppDelegate.swift"
click node_desktop_shell "https://github.com/kimmich4/mobile_frontend/blob/main/linux/runner/main.cc"
click node_web_shell "https://github.com/kimmich4/mobile_frontend/blob/main/web/index.html"
click node_client_tests "https://github.com/kimmich4/mobile_frontend/tree/main/test"
click node_backend_tests "https://github.com/kimmich4/mobile_frontend/tree/main/backend/testing"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lib_main,node_ui_shell,node_viewmodels,node_data_layer,node_api_service,node_repos,node_models,node_theme,node_firebase toneBlue
class node_backend_entry,node_ai_assistant,node_rag_chain,node_rag_logic,node_qdrant,node_ocr,node_plans,node_fallbacks toneAmber
class node_android_shell,node_ios_shell,node_desktop_shell,node_web_shell toneMint
class node_client_tests,node_backend_tests toneRose
```

## Components

### Flutter client

Cross-platform app with presentation, state, and data layers.

- [App entry](https://github.com/kimmich4/mobile_frontend/blob/main/lib/main.dart): Flutter entry · Bootstraps the Flutter application and initial routing. · `lib/main.dart`
- [UI screens](https://github.com/kimmich4/mobile_frontend/tree/main/lib/ui): Presentation layer · Screens and shared widgets for onboarding, auth, home, workout, diet, progress, settings, assistant, and video flows. · `lib/ui`
- [View models](https://github.com/kimmich4/mobile_frontend/tree/main/lib/viewmodels): State layer · Feature state and actions built on a shared base view model. · `lib/viewmodels`
- [Data layer](https://github.com/kimmich4/mobile_frontend/tree/main/lib/data): Repositories and services · Feature repositories, models, and network service boundary. · `lib/data`
- [API service](https://github.com/kimmich4/mobile_frontend/blob/main/lib/data/services/api_service.dart): HTTP gateway · Central network abstraction used by client repositories. · `lib/data/services/api_service.dart`
- [Repos](https://github.com/kimmich4/mobile_frontend/tree/main/lib/data/repositories): Feature repositories · Auth, user, workout, diet, and progress access wrappers. · `lib/data/repositories`
- [Domain models](https://github.com/kimmich4/mobile_frontend/tree/main/lib/data/models): Data models · User, workout, diet, progress, and message entities. · `lib/data/models`
- [Theme](https://github.com/kimmich4/mobile_frontend/blob/main/lib/core/theme/theme_manager.dart): UI core · Shared theming and cross-cutting client UI configuration. · `lib/core/theme/theme_manager.dart`
- [Firebase config](https://github.com/kimmich4/mobile_frontend/blob/main/lib/firebase_options.dart): Client config · Firebase options used by the Flutter app. · `lib/firebase_options.dart`

### Node backend

AI, retrieval, OCR, and plan-generation services.

- [Backend entry](https://github.com/kimmich4/mobile_frontend/blob/main/backend/index.js): Node entry · Starts the backend API and wires feature modules together. · `backend/index.js`
- [AI assistant](https://github.com/kimmich4/mobile_frontend/blob/main/backend/ai_assistant.js): Backend feature · Chat-oriented assistant orchestration for the client. · `backend/ai_assistant.js`
- [RAG chain](https://github.com/kimmich4/mobile_frontend/blob/main/backend/rag_chain.js): Retrieval pipeline · Assembles retrieval-augmented generation flow. · `backend/rag_chain.js`
- [RAG logic](https://github.com/kimmich4/mobile_frontend/blob/main/backend/rag_logic.js): Retrieval logic · Supporting retrieval and response logic for assistant workflows. · `backend/rag_logic.js`
- [Qdrant client](https://github.com/kimmich4/mobile_frontend/blob/main/backend/qdrant_client.js): Vector search · Integration with vector retrieval storage/search. · `backend/qdrant_client.js`
- [OCR logic](https://github.com/kimmich4/mobile_frontend/blob/main/backend/ocr_logic.js): Text extraction · Extracts text from images or documents for downstream AI flows. · `backend/ocr_logic.js`
- [Plan generator](https://github.com/kimmich4/mobile_frontend/blob/main/backend/plan_generator.js): Structured generation · Generates workout or diet plans and related structured outputs. · `backend/plan_generator.js`
- [Fallbacks](https://github.com/kimmich4/mobile_frontend/blob/main/backend/fallbacks.js): Resilience layer · Alternative paths when retrieval, OCR, or AI calls fail. · `backend/fallbacks.js`

### Platform shells

Host wrappers for mobile, desktop, and web targets.

- [Android](https://github.com/kimmich4/mobile_frontend/blob/main/android/app/src/main/kotlin/com/example/mobile_frontend/MainActivity.kt): Platform host · Android wrapper for the Flutter client. · `android/app/src/main/kotlin/com/example/mobile_frontend/MainActivity.kt`
- [iOS](https://github.com/kimmich4/mobile_frontend/blob/main/ios/Runner/AppDelegate.swift): Platform host · iOS runner and app host for the Flutter client. · `ios/Runner/AppDelegate.swift`
- [Desktop](https://github.com/kimmich4/mobile_frontend/blob/main/linux/runner/main.cc): Platform host · Linux, macOS, and Windows runner shells for the Flutter client. · `linux/runner/main.cc`
- [Web](https://github.com/kimmich4/mobile_frontend/blob/main/web/index.html): Platform host · Web entry and manifest for browser deployment. · `web/index.html`

### Tests

Client and backend coverage mapped to the main layers.

- [Client tests](https://github.com/kimmich4/mobile_frontend/tree/main/test): Flutter tests · Tests covering models, repositories, services, and view models. · `test`
- [Backend tests](https://github.com/kimmich4/mobile_frontend/tree/main/backend/testing): Node tests · Backend tests covering assistant, RAG, OCR, planning, and fallbacks. · `backend/testing`

## Connections

- App entry → UI screens: boots · Launches the screen layer and app navigation.
- UI screens → View models: binds · Screens delegate state and actions to view models.
- View models → Repos: uses · Feature state reads and writes through repositories.
- Repos → API service: calls · Repositories centralize network access through the API service.
- Repos → Domain models: maps · Repositories convert responses into domain entities.
- View models → Domain models: consumes · View models expose typed domain data to the UI.
- UI screens → Theme: styles · Screens share global theming and UI tokens.
- App entry → Firebase config: configures · App startup includes Firebase client configuration.
- Backend entry → AI assistant: routes · Backend entry wires the assistant subsystem.
- Backend entry → Plan generator: routes · Backend entry exposes structured plan generation.
- Backend entry → OCR logic: routes · Backend entry wires OCR handling.
- AI assistant → RAG chain: uses · Assistant flow depends on the retrieval chain.
- RAG chain → RAG logic: coordinates · Chain assembly delegates retrieval and response logic.
- RAG chain → Qdrant client: retrieves · Retrieval pulls context from vector search.
- OCR logic → RAG logic: feeds · Extracted text can flow into retrieval and assistant logic.
- Plan generator → RAG logic: uses · Plan generation can reuse contextual retrieval and AI logic.
- Fallbacks → AI assistant: backs up · Provides alternative responses when assistant flow fails.
- Fallbacks → OCR logic: backs up · Provides degraded behavior for extraction failures.
- Fallbacks → Plan generator: backs up · Provides degraded behavior for plan generation failures.
- UI screens → Backend entry: calls · Client features reach the backend through network APIs.
- Android → App entry: hosts · Android embeds the Flutter application.
- iOS → App entry: hosts · iOS embeds the Flutter application.
- Desktop → App entry: hosts · Desktop runners embed the Flutter application.
- Web → App entry: hosts · Web target serves the Flutter application.
- Client tests → View models: covers · Client tests validate feature state and behavior.
- Client tests → Repos: covers · Client tests validate repository behavior.
- Client tests → API service: covers · Client tests validate the network boundary.
- Backend tests → AI assistant: covers · Backend tests validate assistant behavior.
- Backend tests → RAG chain: covers · Backend tests validate retrieval orchestration.
- Backend tests → Qdrant client: covers · Backend tests validate vector search integration.
- Backend tests → OCR logic: covers · Backend tests validate extraction logic.
- Backend tests → Plan generator: covers · Backend tests validate plan generation.
