# sathish-create/fitcoachai_app architecture

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

- Interactive diagram: https://gitdiagram.com/sathish-create/fitcoachai_app
- Repository: https://github.com/sathish-create/fitcoachai_app

## Overview

#### 1. System Purpose and Entry Points
FitCoach AI is a cross-platform Flutter fitness-coaching client backed by a Python/FastAPI service. Its central workflow combines on-device pose capture, server-side form analysis, AI coach/diet requests, and Supabase-backed identity/data.
- Mobile bootstrap, dependency initialization, and routing: `mobile/lib/main.dart`
- Backend HTTP application and endpoint host: `backend/main.py`
- Combined local launcher: `run_all.bat`

#### 2. Mobile Application Shell
The Flutter client is the primary user-facing runtime, targeting Android, iOS, desktop, and partial web support. It uses feature-oriented presentation folders, with shared navigation/layout and core services separating UI from external integrations.
- Persistent app layout/navigation boundary: `mobile/lib/shared/widgets/main_layout.dart`
- App-wide HTTP endpoint configuration: `mobile/lib/core/network/api_constants.dart`
- Native Android host entry: `mobile/android/app/src/main/kotlin/com/gymai/fitcoach/MainActivity.kt`

Control flow begins in the app bootstrap, routes users through landing/auth/setup, then presents dashboard and feature screens. Authentication state is managed separately from screens and controls protected versus guest access.
- Authentication state provider: `mobile/lib/features/auth/presentation/providers/auth_provider.dart`
- Login boundary: `mobile/lib/features/auth/presentation/screens/login_screen.dart`
- Setup/onboarding flow: `mobile/lib/features/setup/presentation/screens/setup_screen.dart`

#### 3. Workout and Hybrid Pose-Analysis Pipeline
The workout feature is the core real-time interaction boundary. The mobile client captures camera-based MediaPipe pose landmarks for low-latency feedback, while the backend receives landmarks for exercise validation and rep/form analysis using the same general pose domain.
- Live workout UI and camera/pose integration: `mobile/lib/features/workout/presentation/screens/workout_screen.dart`
- Warmup and workout completion stages: `mobile/lib/features/workout/presentation/screens/warmup_screen.dart`, `mobile/lib/features/workout/presentation/screens/workout_summary_screen.dart`
- Backend request handling: `backend/main.py`

Backend pose processing is organized as an analyzer plus exercise-family rules. This makes the analyzer responsible for dispatching/common landmark interpretation and rule modules responsible for movement-specific conditions.
- Analysis coordinator: `backend/engine/analyzer.py`
- Rule abstraction/base: `backend/engine/rules/abs.py`, `backend/engine/rules/base.py`
- Representative body-part rule modules: `backend/engine/rules/chest.py`, `backend/engine/rules/legs.py`, `backend/engine/rules/full_body.py`

The packaged MediaPipe task is a deployment dependency of the backend, not a remote ML service.
- Pose model asset: `backend/pose_landmarker.task`

#### 4. AI Coach and Remote API Boundary
The mobile API service is the client-side boundary for FastAPI calls, including coach chat, diet generation, pose-landmark processing, session reset, and health checks. The backend in turn uses Google Gemini for natural-language coaching and diet-generation behavior, with credentials supplied outside source control.
- HTTP service: `mobile/lib/core/services/api_service.dart`
- AI/chat interface surfaces: `mobile/lib/features/coach/presentation/screens/coach_screen.dart`, `mobile/lib/features/coach/presentation/widgets/coach_chat_widget.dart`
- Backend API/Gemini integration point: `backend/main.py`

Relevant runtime configuration/dependencies are captured in:
- Backend environment template: `backend/.env.template`
- Python service/ML dependencies: `backend/requirements.txt`

#### 5. Identity, Persistence, and Device Services
Supabase is the external authentication and PostgreSQL/data boundary, supporting email/password and Google sign-in flows. Local preferences, notifications, speech, and exercise catalog loading remain client-side service concerns.
- Supabase integration: `mobile/lib/core/services/supabase_service.dart`
- Local persistence: `mobile/lib/core/services/storage_service.dart`
- Voice input/output: `mobile/lib/core/services/voice_service.dart`

Exercise browsing and workout selection consume a bundled asset catalog rather than requiring the backend.
- Catalog loader: `mobile/lib/core/services/exercise_data_service.dart`
- Exercise data: `mobile/assets/exercises.json`
- Library/exercise entry screens: `mobile/lib/features/library/presentation/screens/library_screen.dart`, `mobile/lib/features/exercises/presentation/screens/exercises_screen.dart`

#### 6. Supporting Fitness Experiences and External Integrations
Feature screens compose the wider coaching journey: dashboard/steps tracking, workout schedules, calculators/diet planning, profile settings, and nearby gym discovery. Gym discovery depends on device location plus TomTom APIs; step tracking depends on device sensors; notifications are local-device scheduling.
- Dashboard and steps: `mobile/lib/features/dashboard/presentation/screens/dashboard_screen.dart`, `mobile/lib/features/dashboard/presentation/screens/steps_screen.dart`
- Planning and calculators: `mobile/lib/features/schedules/presentation/screens/schedules_screen.dart`, `mobile/lib/features/calculators/presentation/screens/calculators_screen.dart`
- Gym discovery: `mobile/lib/features/gyms/presentation/screens/gyms_screen.dart`
- Notification service/state: `mobile/lib/core/services/notification_service.dart`, `mobile/lib/shared/providers/notifications_provider.dart`

Main entry points: [`mobile/lib/shared/widgets/main_layout.dart`](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/shared/widgets/main_layout.dart) (Main layout & navigation), [`mobile/lib/features/auth/presentation/providers/auth_provider.dart`](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/auth/presentation/providers/auth_provider.dart) (Auth state & login), [`mobile/lib/core/services/api_service.dart`](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/core/services/api_service.dart) (API service), [`mobile/lib/features/workout/presentation/screens/workout_screen.dart`](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/workout/presentation/screens/workout_screen.dart) (Live workout capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Flutter Client"]
  node_bootstrap["App bootstrap &amp; routing<br/>Flutter entry<br/>[main.dart]"]
  node_layout["Main layout &amp; navigation<br/>app shell<br/>[main_layout.dart]"]
  node_auth["Auth state &amp; login<br/>identity UI<br/>[auth_provider.dart]"]
  node_setup["Setup onboarding<br/>onboarding UI<br/>[setup_screen.dart]"]
  node_dashboard["Dashboard &amp; steps<br/>fitness UI"]
  node_workout["Live workout capture<br/>camera pose UI"]
  node_workout_completion["Warmup &amp; workout summary<br/>workout stages<br/>[warmup_screen.dart]"]
  node_coach["Coach chat<br/>AI UI<br/>[coach_screen.dart]"]
  node_fitness_planning["Schedules &amp; calculators<br/>planning UI"]
  node_exercise_library["Exercise library<br/>catalog UI"]
  node_api_service["API service<br/>HTTP client<br/>[api_service.dart]"]
  node_local_services["Local device services<br/>client services"]
  node_catalog["Bundled exercise catalog<br/>JSON asset<br/>[exercises.json]"]
end

subgraph group_backend["FastAPI Analysis Service"]
  node_fastapi["FastAPI endpoint host<br/>Python API<br/>[main.py]"]
  node_analyzer["Pose analysis coordinator<br/>analysis engine<br/>[analyzer.py]"]
  node_rules["Exercise-family rules<br/>pose rules<br/>[base.py]"]
  node_pose_model["Pose landmarker model<br/>ML asset"]
end

subgraph group_external["External &amp; Device Boundaries"]
  node_supabase[("Supabase auth &amp; data<br/>identity database")]
  node_gemini{{"Google Gemini<br/>AI provider"}}
  node_device_integrations["Device sensors &amp; TomTom<br/>device/external APIs"]
end

node_bootstrap -->|"starts shell"| node_layout
node_bootstrap -->|"initializes access state"| node_auth
node_auth -->|"new-user flow"| node_setup
node_auth -->|"authenticated access"| node_layout
node_layout -->|"navigates"| node_dashboard
node_layout -->|"opens"| node_workout
node_layout -->|"opens"| node_coach
node_layout -->|"opens"| node_fitness_planning
node_layout -->|"opens"| node_exercise_library
node_exercise_library -->|"loads"| node_catalog
node_workout -->|"completes"| node_workout_completion
node_workout -->|"sends landmarks"| node_api_service
node_coach -->|"sends chat requests"| node_api_service
node_fitness_planning -->|"requests diet/coaching"| node_api_service
node_api_service -->|"HTTP"| node_fastapi
node_fastapi -->|"pose requests"| node_analyzer
node_analyzer -->|"applies exercise rules"| node_rules
node_analyzer -->|"uses"| node_pose_model
node_fastapi -->|"coach &amp; diet generation"| node_gemini
node_auth -->|"sign-in and identity"| node_supabase
node_local_services -->|"uses device capabilities"| node_device_integrations
node_dashboard -->|"reads step sensors"| node_device_integrations

click node_bootstrap "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/main.dart"
click node_layout "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/shared/widgets/main_layout.dart"
click node_auth "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/auth/presentation/providers/auth_provider.dart"
click node_setup "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/setup/presentation/screens/setup_screen.dart"
click node_dashboard "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/dashboard/presentation/screens/dashboard_screen.dart"
click node_workout "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/workout/presentation/screens/workout_screen.dart"
click node_workout_completion "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/workout/presentation/screens/warmup_screen.dart"
click node_coach "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/coach/presentation/screens/coach_screen.dart"
click node_fitness_planning "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/schedules/presentation/screens/schedules_screen.dart"
click node_exercise_library "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/library/presentation/screens/library_screen.dart"
click node_api_service "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/core/services/api_service.dart"
click node_local_services "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/core/services/storage_service.dart"
click node_catalog "https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/assets/exercises.json"
click node_fastapi "https://github.com/sathish-create/fitcoachai_app/blob/main/backend/main.py"
click node_analyzer "https://github.com/sathish-create/fitcoachai_app/blob/main/backend/engine/analyzer.py"
click node_rules "https://github.com/sathish-create/fitcoachai_app/blob/main/backend/engine/rules/base.py"
click node_pose_model "https://github.com/sathish-create/fitcoachai_app/blob/main/backend/pose_landmarker.task"

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_bootstrap,node_layout,node_auth,node_setup,node_dashboard,node_workout,node_workout_completion,node_coach,node_fitness_planning,node_exercise_library,node_api_service,node_local_services,node_catalog toneBlue
class node_fastapi,node_analyzer,node_rules,node_pose_model toneAmber
class node_supabase,node_gemini,node_device_integrations toneMint
```

## Components

### Flutter Client

Cross-platform user runtime.

- [App bootstrap & routing](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/main.dart): Flutter entry · `mobile/lib/main.dart`
- [Main layout & navigation](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/shared/widgets/main_layout.dart): app shell · `mobile/lib/shared/widgets/main_layout.dart`
- [Auth state & login](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/auth/presentation/providers/auth_provider.dart): identity UI · Controls guest and protected access. · `mobile/lib/features/auth/presentation/providers/auth_provider.dart`
- [Setup onboarding](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/setup/presentation/screens/setup_screen.dart): onboarding UI · `mobile/lib/features/setup/presentation/screens/setup_screen.dart`
- [Dashboard & steps](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/dashboard/presentation/screens/dashboard_screen.dart): fitness UI · `mobile/lib/features/dashboard/presentation/screens/dashboard_screen.dart`
- [Live workout capture](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/workout/presentation/screens/workout_screen.dart): camera pose UI · Captures on-device landmarks and delivers workout feedback. · `mobile/lib/features/workout/presentation/screens/workout_screen.dart`
- [Warmup & workout summary](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/workout/presentation/screens/warmup_screen.dart): workout stages · `mobile/lib/features/workout/presentation/screens/warmup_screen.dart`
- [Coach chat](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/coach/presentation/screens/coach_screen.dart): AI UI · `mobile/lib/features/coach/presentation/screens/coach_screen.dart`
- [Schedules & calculators](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/schedules/presentation/screens/schedules_screen.dart): planning UI · `mobile/lib/features/schedules/presentation/screens/schedules_screen.dart`
- [Exercise library](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/features/library/presentation/screens/library_screen.dart): catalog UI · `mobile/lib/features/library/presentation/screens/library_screen.dart`
- [API service](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/core/services/api_service.dart): HTTP client · Calls coaching, diet, pose, reset, and health endpoints. · `mobile/lib/core/services/api_service.dart`
- [Local device services](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/lib/core/services/storage_service.dart): client services · Storage, voice, and local notifications. · `mobile/lib/core/services/storage_service.dart`
- [Bundled exercise catalog](https://github.com/sathish-create/fitcoachai_app/blob/main/mobile/assets/exercises.json): JSON asset · `mobile/assets/exercises.json`

### FastAPI Analysis Service

HTTP, pose analysis, and AI integration.

- [FastAPI endpoint host](https://github.com/sathish-create/fitcoachai_app/blob/main/backend/main.py): Python API · Receives pose analysis and AI coaching requests. · `backend/main.py`
- [Pose analysis coordinator](https://github.com/sathish-create/fitcoachai_app/blob/main/backend/engine/analyzer.py): analysis engine · Dispatches landmark interpretation to exercise rules. · `backend/engine/analyzer.py`
- [Exercise-family rules](https://github.com/sathish-create/fitcoachai_app/blob/main/backend/engine/rules/base.py): pose rules · Movement-specific chest, leg, and full-body validation. · `backend/engine/rules/base.py`
- [Pose landmarker model](https://github.com/sathish-create/fitcoachai_app/blob/main/backend/pose_landmarker.task): ML asset · Packaged backend MediaPipe task. · `backend/pose_landmarker.task`

### External & Device Boundaries

- **Supabase auth & data**: identity database · Email, Google sign-in, and persisted application data.
- **Google Gemini**: AI provider · Generates coach and diet responses.
- **Device sensors & TomTom**: device/external APIs · Supports steps, location-based gyms, and local notifications.

## Connections

- App bootstrap & routing → Main layout & navigation: starts shell
- App bootstrap & routing → Auth state & login: initializes access state
- Auth state & login → Setup onboarding: new-user flow
- Auth state & login → Main layout & navigation: authenticated access
- Main layout & navigation → Dashboard & steps: navigates
- Main layout & navigation → Live workout capture: opens
- Main layout & navigation → Coach chat: opens
- Main layout & navigation → Schedules & calculators: opens
- Main layout & navigation → Exercise library: opens
- Exercise library → Bundled exercise catalog: loads
- Live workout capture → Warmup & workout summary: completes
- Live workout capture → API service: sends landmarks
- Coach chat → API service: sends chat requests
- Schedules & calculators → API service: requests diet/coaching
- API service → FastAPI endpoint host: HTTP
- FastAPI endpoint host → Pose analysis coordinator: pose requests
- Pose analysis coordinator → Exercise-family rules: applies exercise rules
- Pose analysis coordinator → Pose landmarker model: uses
- FastAPI endpoint host → Google Gemini: coach & diet generation
- Auth state & login → Supabase auth & data: sign-in and identity
- Local device services → Device sensors & TomTom: uses device capabilities
- Dashboard & steps → Device sensors & TomTom: reads step sensors