# technodisaster63/liftguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/technodisaster63/liftguard-ai
- Repository: https://github.com/technodisaster63/liftguard-ai

## Overview

LiftGuard is an offline-capable movement coaching platform: a browser starts a session, supplies or selects camera video, and receives live rep counts, form flags, and fatigue feedback; stopping saves a session report. The backend also supports user/face enrollment, settings, analytics, hardware control, and opt-in landmark contributions. The shared analysis engine and movement-mode layer underpin live and recorded-video analysis. Several relationships are documented in the README or visible in excerpts; unsampled feature implementations are represented at their supported paths, without inferring internal calls.

Main entry points: [`backend/app/main.py`](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/routes_sessions.py`](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_sessions.py) (Session routes), [`backend/app/core/session_manager.py`](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/session_manager.py) (Session manager), [`backend/app/core/liftguard_engine.py`](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/liftguard_engine.py) (LiftGuard engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser dashboard"]
  node_browser["Dashboard<br/>[page.tsx]"]
  node_live_ui["Live coaching UI<br/>[page.tsx]"]
  node_history_ui["Sessions and reports<br/>[page.tsx]"]
  node_settings_ui["Settings UI<br/>[page.tsx]"]
  node_users_ui["User and enrollment UI<br/>[page.tsx]"]
  node_hardware_ui["Hardware UI<br/>[page.tsx]"]
  node_contrib_ui["Contribution UI<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_ws_client["Live socket client<br/>[ws.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_session_routes["Session routes<br/>[routes_sessions.py]"]
  node_live_socket["Live WebSocket<br/>[ws_live.py]"]
  node_settings_routes["Settings routes<br/>[routes_settings.py]"]
  node_analytics_routes["Analytics routes"]
  node_users_routes["User routes<br/>[routes_users.py]"]
  node_hardware_routes["Hardware routes<br/>[routes_hardware.py]"]
  node_contrib_routes["Contribution routes<br/>[routes_contrib.py]"]
end

subgraph group_analysis["Movement analysis"]
  node_session_manager["Session manager<br/>[session_manager.py]"]
  node_engine["LiftGuard engine"]
  node_live_feed["Live movement feed<br/>[live.py]"]
  node_movement_modes["Movement modes<br/>[movements.py]"]
  node_auto_mode["Automatic mode<br/>[auto_mode.py]"]
  node_analyzer["Video analyzer<br/>[analyzer.py]"]
  node_fatigue["Fatigue tracking<br/>[fatigue_engine.py]"]
  node_risk["Risk index"]
end

subgraph group_records["Identity and records"]
  node_user_manager["Local user manager"]
  node_face_id["Face ID<br/>[face_id.py]"]
  node_session_db[("Session history store<br/>[database.py]")]
  node_settings_store["Settings store<br/>[settings_store.py]"]
  node_contrib_store[("Landmark contribution store<br/>[store.py]")]
end

subgraph group_integrations["Optional integrations"]
  node_arduino["Arduino controller"]
end

node_athlete(("Lifter"))
node_camera(("Camera"))
node_video["Video file"]

node_athlete -->|"uses"| node_browser
node_browser -->|"requests"| node_api_client
node_live_ui -->|"streams frames"| node_ws_client
node_api_client -->|"calls API"| node_fastapi
node_ws_client -->|"exchanges live data"| node_live_socket
node_fastapi -->|"registers router"| node_session_routes
node_fastapi -->|"registers router"| node_live_socket
node_fastapi -->|"registers router"| node_users_routes
node_fastapi -->|"registers router"| node_hardware_routes
node_fastapi -->|"registers router"| node_analytics_routes
node_fastapi -->|"registers router"| node_settings_routes
node_fastapi -->|"registers router"| node_contrib_routes
node_session_routes -->|"starts session"| node_session_manager
node_session_routes -->|"persists reports"| node_session_db
node_session_routes -->|"records contributions"| node_contrib_store
node_session_routes -->|"validates mode"| node_movement_modes
node_session_manager -->|"constructs"| node_engine
node_camera -->|"provides frames"| node_session_manager
node_video -->|"analyzes clip"| node_analyzer
node_session_manager -->|"runs live analysis"| node_live_feed
node_live_feed -->|"uses selected mode"| node_movement_modes
node_engine -->|"uses"| node_auto_mode
node_auto_mode -->|"selects mode"| node_movement_modes
node_engine -->|"updates"| node_fatigue
node_engine -->|"computes risk"| node_risk
node_session_manager -->|"identifies lifter"| node_user_manager
node_user_manager -->|"uses embeddings"| node_face_id
node_users_routes -->|"manages users"| node_user_manager
node_analytics_routes -->|"queries sessions"| node_session_routes
node_settings_ui -->|"configures sessions"| node_settings_routes
node_settings_routes -->|"reads and writes"| node_settings_store
node_hardware_ui -->|"controls hardware"| node_hardware_routes
node_hardware_routes -.->|"controls device"| node_arduino
node_contrib_ui -->|"submits contribution"| node_contrib_routes
node_contrib_routes -->|"stores landmarks"| node_contrib_store
node_users_ui -->|"registers lifter"| node_users_routes

click node_browser "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/dashboard/page.tsx"
click node_live_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/live/page.tsx"
click node_history_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/sessions/page.tsx"
click node_settings_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/settings/page.tsx"
click node_users_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/register/page.tsx"
click node_hardware_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/hardware/page.tsx"
click node_contrib_ui "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/contributions/page.tsx"
click node_api_client "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/lib/api.ts"
click node_ws_client "https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/lib/ws.ts"
click node_fastapi "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/main.py"
click node_session_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_sessions.py"
click node_live_socket "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/ws_live.py"
click node_settings_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_settings.py"
click node_analytics_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_analytics.py"
click node_users_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_users.py"
click node_hardware_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_hardware.py"
click node_contrib_routes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_contrib.py"
click node_session_manager "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/session_manager.py"
click node_engine "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/liftguard_engine.py"
click node_live_feed "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/live.py"
click node_movement_modes "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/movements.py"
click node_auto_mode "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/auto_mode.py"
click node_analyzer "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/analyzer.py"
click node_fatigue "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/tracking/fatigue_engine.py"
click node_risk "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/ml/injury_risk_index_v2.py"
click node_user_manager "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/identity/user_manager_lite.py"
click node_face_id "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/identity/face_id.py"
click node_session_db "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/db/database.py"
click node_settings_store "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/settings_store.py"
click node_contrib_store "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/contrib/store.py"
click node_arduino "https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/hardware/arduino_controller.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_browser,node_live_ui,node_history_ui,node_settings_ui,node_users_ui,node_hardware_ui,node_contrib_ui,node_api_client,node_ws_client toneBlue
class node_fastapi,node_session_routes,node_live_socket,node_settings_routes,node_analytics_routes,node_users_routes,node_hardware_routes,node_contrib_routes toneAmber
class node_session_manager,node_engine,node_live_feed,node_movement_modes,node_auto_mode,node_analyzer,node_fatigue,node_risk toneMint
class node_user_manager,node_face_id,node_session_db,node_settings_store,node_contrib_store toneRose
class node_arduino,node_athlete,node_camera,node_video toneIndigo
```

## Components

### Browser dashboard

- [Dashboard](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Live coaching UI](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/live/page.tsx): `frontend/app/live/page.tsx`
- [Sessions and reports](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/sessions/page.tsx): `frontend/app/sessions/page.tsx`
- [Settings UI](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/settings/page.tsx): `frontend/app/settings/page.tsx`
- [User and enrollment UI](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/register/page.tsx): `frontend/app/register/page.tsx`
- [Hardware UI](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/hardware/page.tsx): `frontend/app/hardware/page.tsx`
- [Contribution UI](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/app/contributions/page.tsx): `frontend/app/contributions/page.tsx`
- [API client](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Live socket client](https://github.com/technodisaster63/liftguard-ai/blob/main/frontend/lib/ws.ts): `frontend/lib/ws.ts`

### Backend API

- [FastAPI application](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Session routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_sessions.py): `backend/app/api/routes_sessions.py`
- [Live WebSocket](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/ws_live.py): `backend/app/api/ws_live.py`
- [Settings routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_settings.py): `backend/app/api/routes_settings.py`
- [Analytics routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_analytics.py): `backend/app/api/routes_analytics.py`
- [User routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_users.py): `backend/app/api/routes_users.py`
- [Hardware routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_hardware.py): `backend/app/api/routes_hardware.py`
- [Contribution routes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/api/routes_contrib.py): `backend/app/api/routes_contrib.py`

### Movement analysis

- [Session manager](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/session_manager.py): `backend/app/core/session_manager.py`
- [LiftGuard engine](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/liftguard_engine.py): `backend/app/core/liftguard_engine.py`
- [Live movement feed](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/live.py): `backend/app/video_analysis/live.py`
- [Movement modes](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/movements.py): `backend/app/video_analysis/movements.py`
- [Automatic mode](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/auto_mode.py): `backend/app/video_analysis/auto_mode.py`
- [Video analyzer](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/video_analysis/analyzer.py): `backend/app/video_analysis/analyzer.py`
- [Fatigue tracking](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/tracking/fatigue_engine.py): `backend/app/tracking/fatigue_engine.py`
- [Risk index](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/ml/injury_risk_index_v2.py): `backend/app/ml/injury_risk_index_v2.py`

### Identity and records

- [Local user manager](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/identity/user_manager_lite.py): `backend/app/identity/user_manager_lite.py`
- [Face ID](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/identity/face_id.py): `backend/app/identity/face_id.py`
- [Session history store](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Settings store](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/core/settings_store.py): `backend/app/core/settings_store.py`
- [Landmark contribution store](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/contrib/store.py): `backend/app/contrib/store.py`

### Optional integrations

- [Arduino controller](https://github.com/technodisaster63/liftguard-ai/blob/main/backend/app/hardware/arduino_controller.py): `backend/app/hardware/arduino_controller.py`

### Other components

- **Lifter**
- **Camera**
- **Video file**

## Connections

- Lifter → Dashboard: uses (evidence: `README.md`)
- Dashboard → API client: requests (evidence: `frontend/app/dashboard/page.tsx`)
- Live coaching UI → Live socket client: streams frames (evidence: `README.md`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- Live socket client → Live WebSocket: exchanges live data (evidence: `README.md`)
- FastAPI application → Session routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Live WebSocket: registers router (evidence: `backend/app/main.py`)
- FastAPI application → User routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Hardware routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Analytics routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Settings routes: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Contribution routes: registers router (evidence: `backend/app/main.py`)
- Session routes → Session manager: starts session (evidence: `backend/app/api/routes_sessions.py`)
- Session routes → Session history store: persists reports (evidence: `backend/app/api/routes_sessions.py`)
- Session routes → Landmark contribution store: records contributions (evidence: `backend/app/api/routes_sessions.py`)
- Session routes → Movement modes: validates mode (evidence: `backend/app/api/routes_sessions.py`)
- Session manager → LiftGuard engine: constructs (evidence: `backend/app/core/session_manager.py`)
- Camera → Session manager: provides frames (evidence: `README.md`)
- Video file → Video analyzer: analyzes clip (evidence: `README.md`)
- Session manager → Live movement feed: runs live analysis (evidence: `README.md`)
- Live movement feed → Movement modes: uses selected mode (evidence: `backend/app/video_analysis/movements.py`)
- LiftGuard engine → Automatic mode: uses (evidence: `backend/app/core/liftguard_engine.py`)
- Automatic mode → Movement modes: selects mode (evidence: `backend/app/video_analysis/auto_mode.py`)
- LiftGuard engine → Fatigue tracking: updates (evidence: `backend/app/core/liftguard_engine.py`)
- LiftGuard engine → Risk index: computes risk (evidence: `backend/app/core/liftguard_engine.py`)
- Session manager → Local user manager: identifies lifter (evidence: `backend/app/core/session_manager.py`)
- Local user manager → Face ID: uses embeddings (evidence: `backend/app/identity/user_manager_lite.py`)
- User routes → Local user manager: manages users (evidence: `backend/app/api/routes_users.py`)
- Analytics routes → Session routes: queries sessions (evidence: `backend/app/api/routes_analytics.py`)
- Settings UI → Settings routes: configures sessions (evidence: `README.md`)
- Settings routes → Settings store: reads and writes (evidence: `backend/app/api/routes_settings.py`)
- Hardware UI → Hardware routes: controls hardware (evidence: `README.md`)
- Hardware routes → Arduino controller: controls device
- Contribution UI → Contribution routes: submits contribution (evidence: `README.md`)
- Contribution routes → Landmark contribution store: stores landmarks (evidence: `backend/app/api/routes_contrib.py`)
- User and enrollment UI → User routes: registers lifter (evidence: `README.md`)
