# ksrdhilip/adhils-fitness architecture

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

- Interactive diagram: https://gitdiagram.com/ksrdhilip/adhils-fitness
- Repository: https://github.com/ksrdhilip/adhils-fitness

## Overview

ADhils Fitness is a profile-based workout planning, logging, and coaching app, with shared Kotlin UI/core logic, Android platform integrations, and an optional local PC AI companion. The main user path is profile setup and check-in, session generation, set logging, and review of summaries or progress. The README also documents camera coaching, exercise guidance, backups, health integrations, and the companion. Some subsystem links are documented but their implementation was not sampled; those links are marked dashed where source evidence is unavailable.

Main entry points: [`shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt) (Fitness UI), [`shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt) (Workout screens), [`companion/src/server.mjs`](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/server.mjs) (PC coach server), [`core/src/main/kotlin/com/adhils/fitness/core/Training.kt`](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Training.kt) (Workout planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["App entry<br/>[MainActivity.kt]"]
  node_ui["Fitness UI<br/>[FitnessApp.kt]"]
  node_viewmodel["App state"]
  node_onboarding["Profile setup"]
  node_workouts["Workout screens<br/>[WorkoutScreens.kt]"]
  node_progress["Progress views"]
  node_guidance["Exercise guidance<br/>[HowToScreen.kt]"]
  node_camera_ui["Camera coaching UI"]
end

subgraph group_training["Training domain"]
  node_catalog["Exercise catalog<br/>[Catalog.kt]"]
  node_training_engine["Workout planning<br/>[Training.kt]"]
  node_recovery["Recovery analysis<br/>[Recovery.kt]"]
  node_coach["Coach proposals<br/>[Coach.kt]"]
  node_pose["Pose analysis<br/>[PoseEngine.kt]"]
end

subgraph group_platform["Platform services"]
  node_camera_preview["Android camera"]
  node_health_connect["Health Connect"]
  node_wearables["Wearable sync"]
  node_backup["Encrypted backup<br/>[Backup.kt]"]
  node_companion_client["Phone companion client<br/>[CompanionClient.kt]"]
end

subgraph group_companion["AI companion"]
  node_pc_server["PC coach server<br/>[server.mjs]"]
  node_contracts["Request validation<br/>[contracts.mjs]"]
  node_journal[("Budget journal<br/>[journal.mjs]")]
  node_providers["AI providers<br/>[providers.mjs]"]
  node_codex["Codex client<br/>[codex.mjs]"]
end

node_user(("Fitness user"))
node_ai_service{{"Selected AI service"}}
node_health_service{{"Health Connect service"}}

node_user -->|"opens"| node_app
node_app -->|"launches"| node_ui
node_ui -->|"uses state"| node_viewmodel
node_ui -->|"routes to"| node_onboarding
node_ui -->|"routes to"| node_workouts
node_ui -.->|"shows"| node_progress
node_ui -->|"routes to"| node_guidance
node_ui -->|"routes to"| node_camera_ui
node_workouts -->|"updates state"| node_viewmodel
node_workouts -->|"uses planning"| node_training_engine
node_workouts -->|"reads exercises"| node_catalog
node_workouts -->|"reads recovery"| node_recovery
node_workouts -->|"uses proposals"| node_coach
node_onboarding -->|"uses planning"| node_training_engine
node_training_engine -->|"selects exercises"| node_catalog
node_training_engine -->|"uses recovery"| node_recovery
node_recovery -->|"reads exercises"| node_catalog
node_coach -->|"calculates loads"| node_training_engine
node_coach -->|"validates exercises"| node_catalog
node_camera_ui -->|"uses state"| node_viewmodel
node_camera_ui -->|"sends pose frames"| node_pose
node_camera_preview -.->|"provides frames"| node_camera_ui
node_health_connect -.->|"reads records"| node_health_service
node_wearables -->|"requests vitals"| node_health_connect
node_user -.->|"exports or imports"| node_backup
node_companion_client -.->|"sends coach requests"| node_pc_server
node_pc_server -->|"validates requests"| node_contracts
node_pc_server -->|"reserves budget"| node_journal
node_pc_server -.->|"dispatches requests"| node_providers
node_pc_server -.->|"dispatches requests"| node_codex
node_providers -.->|"calls provider"| node_ai_service
node_codex -.->|"calls Codex"| node_ai_service

click node_app "https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/MainActivity.kt"
click node_ui "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt"
click node_viewmodel "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/FitnessViewModel.kt"
click node_onboarding "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/OnboardingQuestions.kt"
click node_workouts "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt"
click node_progress "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/ExerciseProgressScreens.kt"
click node_guidance "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/HowToScreen.kt"
click node_camera_ui "https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/CameraCoachScreen.kt"
click node_catalog "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Catalog.kt"
click node_training_engine "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Training.kt"
click node_recovery "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Recovery.kt"
click node_coach "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Coach.kt"
click node_pose "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/PoseEngine.kt"
click node_camera_preview "https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/AndroidCameraPreview.kt"
click node_health_connect "https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/HealthConnectManager.kt"
click node_wearables "https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/HealthWearableManager.kt"
click node_backup "https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/jvmMain/kotlin/com/adhils/fitness/core/Backup.kt"
click node_companion_client "https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/CompanionClient.kt"
click node_pc_server "https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/server.mjs"
click node_contracts "https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/contracts.mjs"
click node_journal "https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/journal.mjs"
click node_providers "https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/providers.mjs"
click node_codex "https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/codex.mjs"

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_app,node_ui,node_viewmodel,node_onboarding,node_workouts,node_progress,node_guidance,node_camera_ui,node_user toneBlue
class node_catalog,node_training_engine,node_recovery,node_coach,node_pose toneAmber
class node_camera_preview,node_health_connect,node_wearables,node_backup,node_companion_client toneMint
class node_pc_server,node_contracts,node_journal,node_providers,node_codex toneRose
class node_ai_service,node_health_service toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/MainActivity.kt): `app/src/main/java/com/adhils/fitness/MainActivity.kt`
- [Fitness UI](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`
- [App state](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/FitnessViewModel.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessViewModel.kt`
- [Profile setup](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/OnboardingQuestions.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/OnboardingQuestions.kt`
- [Workout screens](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`
- [Progress views](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/ExerciseProgressScreens.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/ExerciseProgressScreens.kt`
- [Exercise guidance](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/HowToScreen.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/HowToScreen.kt`
- [Camera coaching UI](https://github.com/ksrdhilip/adhils-fitness/blob/main/shared/src/commonMain/kotlin/com/adhils/fitness/CameraCoachScreen.kt): `shared/src/commonMain/kotlin/com/adhils/fitness/CameraCoachScreen.kt`

### Training domain

- [Exercise catalog](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Catalog.kt): `core/src/main/kotlin/com/adhils/fitness/core/Catalog.kt`
- [Workout planning](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Training.kt): `core/src/main/kotlin/com/adhils/fitness/core/Training.kt`
- [Recovery analysis](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Recovery.kt): `core/src/main/kotlin/com/adhils/fitness/core/Recovery.kt`
- [Coach proposals](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/Coach.kt): `core/src/main/kotlin/com/adhils/fitness/core/Coach.kt`
- [Pose analysis](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/main/kotlin/com/adhils/fitness/core/PoseEngine.kt): `core/src/main/kotlin/com/adhils/fitness/core/PoseEngine.kt`

### Platform services

- [Android camera](https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/AndroidCameraPreview.kt): `app/src/main/java/com/adhils/fitness/AndroidCameraPreview.kt`
- [Health Connect](https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/HealthConnectManager.kt): `app/src/main/java/com/adhils/fitness/HealthConnectManager.kt`
- [Wearable sync](https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/HealthWearableManager.kt): `app/src/main/java/com/adhils/fitness/HealthWearableManager.kt`
- [Encrypted backup](https://github.com/ksrdhilip/adhils-fitness/blob/main/core/src/jvmMain/kotlin/com/adhils/fitness/core/Backup.kt): `core/src/jvmMain/kotlin/com/adhils/fitness/core/Backup.kt`
- [Phone companion client](https://github.com/ksrdhilip/adhils-fitness/blob/main/app/src/main/java/com/adhils/fitness/CompanionClient.kt): `app/src/main/java/com/adhils/fitness/CompanionClient.kt`

### AI companion

- [PC coach server](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/server.mjs): `companion/src/server.mjs`
- [Request validation](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/contracts.mjs): `companion/src/contracts.mjs`
- [Budget journal](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/journal.mjs): `companion/src/journal.mjs`
- [AI providers](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/providers.mjs): `companion/src/providers.mjs`
- [Codex client](https://github.com/ksrdhilip/adhils-fitness/blob/main/companion/src/codex.mjs): `companion/src/codex.mjs`

### Other components

- **Fitness user**
- **Selected AI service**
- **Health Connect service**

## Connections

- Fitness user → App entry: opens (evidence: `README.md`)
- App entry → Fitness UI: launches (evidence: `app/src/main/java/com/adhils/fitness/MainActivity.kt`)
- Fitness UI → App state: uses state (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`)
- Fitness UI → Profile setup: routes to (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`)
- Fitness UI → Workout screens: routes to (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`)
- Fitness UI → Progress views: shows (evidence: `README.md`)
- Fitness UI → Exercise guidance: routes to (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`)
- Fitness UI → Camera coaching UI: routes to (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/FitnessApp.kt`)
- Workout screens → App state: updates state (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`)
- Workout screens → Workout planning: uses planning (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`)
- Workout screens → Exercise catalog: reads exercises (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`)
- Workout screens → Recovery analysis: reads recovery (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`)
- Workout screens → Coach proposals: uses proposals (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/WorkoutScreens.kt`)
- Profile setup → Workout planning: uses planning (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/OnboardingQuestions.kt`)
- Workout planning → Exercise catalog: selects exercises (evidence: `core/src/main/kotlin/com/adhils/fitness/core/Training.kt`)
- Workout planning → Recovery analysis: uses recovery (evidence: `core/src/main/kotlin/com/adhils/fitness/core/Training.kt`)
- Recovery analysis → Exercise catalog: reads exercises (evidence: `core/src/main/kotlin/com/adhils/fitness/core/Recovery.kt`)
- Coach proposals → Workout planning: calculates loads (evidence: `core/src/main/kotlin/com/adhils/fitness/core/Coach.kt`)
- Coach proposals → Exercise catalog: validates exercises (evidence: `core/src/main/kotlin/com/adhils/fitness/core/Coach.kt`)
- Camera coaching UI → App state: uses state (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/CameraCoachScreen.kt`)
- Camera coaching UI → Pose analysis: sends pose frames (evidence: `shared/src/commonMain/kotlin/com/adhils/fitness/CameraCoachScreen.kt`)
- Android camera → Camera coaching UI: provides frames
- Health Connect → Health Connect service: reads records (evidence: `app/src/main/java/com/adhils/fitness/HealthConnectManager.kt`)
- Wearable sync → Health Connect: requests vitals (evidence: `app/src/main/java/com/adhils/fitness/HealthWearableManager.kt`)
- Fitness user → Encrypted backup: exports or imports (evidence: `README.md`)
- Phone companion client → PC coach server: sends coach requests (evidence: `README.md`)
- PC coach server → Request validation: validates requests (evidence: `companion/src/server.mjs`)
- PC coach server → Budget journal: reserves budget (evidence: `companion/src/server.mjs`)
- PC coach server → AI providers: dispatches requests
- PC coach server → Codex client: dispatches requests
- AI providers → Selected AI service: calls provider
- Codex client → Selected AI service: calls Codex
