# aman05cody/repsense---ai-gym-coach architecture

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

- Interactive diagram: https://gitdiagram.com/aman05cody/repsense---ai-gym-coach
- Repository: https://github.com/aman05cody/repsense---ai-gym-coach

## Overview

RepSense is a Streamlit workout coach: a user creates a profile, chooses an exercise and targets, then trains in front of a camera while pose-based detectors count reps and report form metrics. The app synchronizes progress, records completed sets, and presents workout history; coaching feedback can be generated by Groq and spoken aloud. The graph preserves all five exercise detectors and the shared exercise abstraction. Main-to-runtime wiring beyond the shown excerpt is marked unverified where necessary; documented product capabilities are retained without implying unsampled calls.

Main entry points: [`services/vision/exercise_video_processor.py`](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/vision/exercise_video_processor.py) (Video processor), [`main.py`](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/main.py) (Streamlit dashboard), [`services/tracking/metrics.py`](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/tracking/metrics.py) (Metrics and set sync), [`core/base_exercise.py`](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/core/base_exercise.py) (Exercise abstraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Workout app"]
  node_main["Streamlit dashboard<br/>[main.py]"]
  node_session["Session defaults"]
  node_ui["Theme and styles<br/>[style_loader.py]"]
end

subgraph group_vision["Pose analysis"]
  node_processor["Video processor"]
  node_model["Pose landmarker"]
  node_base["Exercise abstraction<br/>[base_exercise.py]"]
  node_squat["Squat detector<br/>[squat.py]"]
  node_pushup["Push-up detector<br/>[pushup.py]"]
  node_curl["Biceps curl detector<br/>[biceps_curl.py]"]
  node_press["Shoulder press detector<br/>[shoulder_press.py]"]
  node_lunge["Lunge detector<br/>[lunges.py]"]
end

subgraph group_tracking["Workout tracking"]
  node_config["Workout configuration<br/>[workout_config.py]"]
  node_metrics["Metrics and set sync<br/>[metrics.py]"]
end

subgraph group_coaching["AI coaching"]
  node_voice["Voice pipeline<br/>[voice_pipeline.py]"]
  node_llm["LLM coach<br/>[llm.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_persistence["Profiles and history"]
  node_auth["Login wall<br/>[login_wall.py]"]
  node_repo["Exercise repository"]
  node_sqlite[("Workout database")]
end

node_user(("Athlete"))
node_camera(("Browser camera"))
node_groq{{"Groq API"}}

node_user -->|"uses"| node_main
node_main -->|"renders login"| node_auth
node_auth -->|"gets or creates profile"| node_repo
node_main -->|"initializes and reads history"| node_repo
node_repo -->|"reads and writes"| node_sqlite
node_main -.->|"initializes state"| node_session
node_main -->|"loads styling"| node_ui
node_main -->|"uses exercise options"| node_config
node_camera -->|"streams frames"| node_processor
node_main -.->|"starts video processing"| node_processor
node_processor -->|"loads pose model"| node_model
node_processor -->|"uses pose connections"| node_config
node_processor -->|"dispatches by exercise"| node_squat
node_processor -->|"dispatches by exercise"| node_pushup
node_processor -->|"dispatches by exercise"| node_curl
node_processor -->|"dispatches by exercise"| node_press
node_processor -->|"dispatches by exercise"| node_lunge
node_squat -.->|"inherits from"| node_base
node_pushup -.->|"inherits from"| node_base
node_curl -->|"inherits from"| node_base
node_press -.->|"inherits from"| node_base
node_lunge -.->|"inherits from"| node_base
node_main -->|"syncs progress"| node_metrics
node_metrics -->|"reads latest metrics"| node_processor
node_metrics -->|"selects metric fields"| node_config
node_metrics -->|"saves completed sets"| node_repo
node_main -->|"creates coaching pipeline"| node_voice
node_metrics -->|"requests event feedback"| node_voice
node_voice -->|"requests feedback"| node_llm
node_voice -->|"synthesizes speech"| node_tts
node_llm -->|"uses coaching prompt"| node_config
node_llm -->|"sends chat request"| node_groq

click node_main "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/main.py"
click node_session "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/state/session_defaults.py"
click node_ui "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/ui/style_loader.py"
click node_auth "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/auth/login_wall.py"
click node_repo "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/persistence/exercise_repository.py"
click node_config "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/config/workout_config.py"
click node_metrics "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/tracking/metrics.py"
click node_processor "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/vision/exercise_video_processor.py"
click node_model "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/ml_models/pose_landmarker_full.task"
click node_base "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/core/base_exercise.py"
click node_squat "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/squat.py"
click node_pushup "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/pushup.py"
click node_curl "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/biceps_curl.py"
click node_press "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/shoulder_press.py"
click node_lunge "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/lunges.py"
click node_voice "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/voice_pipeline.py"
click node_llm "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/llm.py"
click node_tts "https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/tts.py"

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_main,node_session,node_ui,node_camera toneBlue
class node_processor,node_model,node_base,node_squat,node_pushup,node_curl,node_press,node_lunge toneAmber
class node_config,node_metrics,node_groq toneMint
class node_voice,node_llm,node_tts toneRose
class node_auth,node_repo,node_sqlite,node_user toneIndigo
```

## Components

### Workout app

- [Streamlit dashboard](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/main.py): `main.py`
- [Session defaults](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/state/session_defaults.py): `services/state/session_defaults.py`
- [Theme and styles](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/ui/style_loader.py): `services/ui/style_loader.py`

### Pose analysis

- [Video processor](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/vision/exercise_video_processor.py): `services/vision/exercise_video_processor.py`
- [Pose landmarker](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/ml_models/pose_landmarker_full.task): `ml_models/pose_landmarker_full.task`
- [Exercise abstraction](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/core/base_exercise.py): `core/base_exercise.py`
- [Squat detector](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/squat.py): `detectors/squat.py`
- [Push-up detector](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/pushup.py): `detectors/pushup.py`
- [Biceps curl detector](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/biceps_curl.py): `detectors/biceps_curl.py`
- [Shoulder press detector](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/shoulder_press.py): `detectors/shoulder_press.py`
- [Lunge detector](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/detectors/lunges.py): `detectors/lunges.py`

### Workout tracking

- [Workout configuration](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/config/workout_config.py): `services/config/workout_config.py`
- [Metrics and set sync](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/tracking/metrics.py): `services/tracking/metrics.py`

### AI coaching

- [Voice pipeline](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/voice_pipeline.py): `services/coaching/voice_pipeline.py`
- [LLM coach](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/llm.py): `services/coaching/llm.py`
- [Speech synthesis](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/coaching/tts.py): `services/coaching/tts.py`

### Profiles and history

- [Login wall](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/auth/login_wall.py): `services/auth/login_wall.py`
- [Exercise repository](https://github.com/aman05cody/repsense---ai-gym-coach/blob/main/services/persistence/exercise_repository.py): `services/persistence/exercise_repository.py`
- **Workout database**

### Other components

- **Athlete**
- **Browser camera**
- **Groq API**

## Connections

- Athlete → Streamlit dashboard: uses (evidence: `README.md`)
- Streamlit dashboard → Login wall: renders login (evidence: `main.py`)
- Login wall → Exercise repository: gets or creates profile (evidence: `services/auth/login_wall.py`)
- Streamlit dashboard → Exercise repository: initializes and reads history (evidence: `main.py`)
- Exercise repository → Workout database: reads and writes (evidence: `services/persistence/exercise_repository.py`)
- Streamlit dashboard → Session defaults: initializes state (evidence: `main.py`)
- Streamlit dashboard → Theme and styles: loads styling (evidence: `main.py`)
- Streamlit dashboard → Workout configuration: uses exercise options (evidence: `main.py`)
- Browser camera → Video processor: streams frames (evidence: `README.md`)
- Streamlit dashboard → Video processor: starts video processing (evidence: `main.py`)
- Video processor → Pose landmarker: loads pose model (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Workout configuration: uses pose connections (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Squat detector: dispatches by exercise (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Push-up detector: dispatches by exercise (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Biceps curl detector: dispatches by exercise (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Shoulder press detector: dispatches by exercise (evidence: `services/vision/exercise_video_processor.py`)
- Video processor → Lunge detector: dispatches by exercise (evidence: `services/vision/exercise_video_processor.py`)
- Squat detector → Exercise abstraction: inherits from (evidence: `detectors/squat.py`)
- Push-up detector → Exercise abstraction: inherits from (evidence: `detectors/pushup.py`)
- Biceps curl detector → Exercise abstraction: inherits from (evidence: `detectors/biceps_curl.py`)
- Shoulder press detector → Exercise abstraction: inherits from (evidence: `detectors/shoulder_press.py`)
- Lunge detector → Exercise abstraction: inherits from (evidence: `detectors/lunges.py`)
- Streamlit dashboard → Metrics and set sync: syncs progress (evidence: `main.py`)
- Metrics and set sync → Video processor: reads latest metrics (evidence: `services/tracking/metrics.py`)
- Metrics and set sync → Workout configuration: selects metric fields (evidence: `services/tracking/metrics.py`)
- Metrics and set sync → Exercise repository: saves completed sets (evidence: `services/tracking/metrics.py`)
- Streamlit dashboard → Voice pipeline: creates coaching pipeline (evidence: `main.py`)
- Metrics and set sync → Voice pipeline: requests event feedback (evidence: `services/tracking/metrics.py`)
- Voice pipeline → LLM coach: requests feedback (evidence: `services/coaching/voice_pipeline.py`)
- Voice pipeline → Speech synthesis: synthesizes speech (evidence: `services/coaching/voice_pipeline.py`)
- LLM coach → Workout configuration: uses coaching prompt (evidence: `services/coaching/llm.py`)
- LLM coach → Groq API: sends chat request (evidence: `services/coaching/llm.py`)
