# kakumanu-harshitha/fitvision-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kakumanu-harshitha/fitvision-ai
- Repository: https://github.com/kakumanu-harshitha/fitvision-ai

## Overview

#### Purpose and Runtime Entry Points
AI Fitness Tracker is a full-stack fitness coaching system: browser-based pose/workout interaction, FastAPI APIs, persisted fitness/social data, and AI-assisted personalization/coaching. Backend starts at `Ai_Fitness_Tracker/backend/app/main.py` (`uvicorn app.main:app`); React starts from `Ai_Fitness_Tracker/frontend/src/index.js` and composes routes/UI in `Ai_Fitness_Tracker/frontend/src/App.js`.

#### Client Application and Live Workout Boundary
The React client owns interactive screens, camera presentation, local workout state, and API/WebSocket consumption. Live sessions center on `Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js` and `Ai_Fitness_Tracker/frontend/src/components/CameraView.js`; shared state is provided through `Ai_Fitness_Tracker/frontend/src/contexts/WorkoutContext.js`. The browser-side MediaPipe workflow is the real-time pose boundary; it emits workout outcomes rather than requiring raw camera streams to be persisted by the backend.

#### HTTP API, Authentication, and Domain Routing
FastAPI versioned routers expose auth, workouts, plans, dashboards, social, AI, chatbot, hydration, and voice-facing capabilities under `Ai_Fitness_Tracker/backend/app/api/v1/`. Authentication/security dependencies and request policy are centralized in `Ai_Fitness_Tracker/backend/app/api/dependencies.py`, `Ai_Fitness_Tracker/backend/app/core/security.py`, and `Ai_Fitness_Tracker/backend/app/core/middleware.py`. JWT is the primary auth mechanism, with migration evidence for optional TOTP MFA.

#### Business Services and Persistence
Router handlers delegate core workout, activity, plan, and identity behaviors to service/repository layers: `Ai_Fitness_Tracker/backend/app/services/workout_service.py`, `Ai_Fitness_Tracker/backend/app/services/activity_service.py`, and `Ai_Fitness_Tracker/backend/app/db/repositories/workout_repo.py`. SQLAlchemy models and async database setup form the persistence boundary in `Ai_Fitness_Tracker/backend/app/db/models.py` and `Ai_Fitness_Tracker/backend/app/db/database.py`. Alembic migrations in `Ai_Fitness_Tracker/backend/alembic/versions/` evolve the relational schema, including workout replay, plans, chatbot context, and social activity.

#### Computer-Vision Exercise Pipeline
The backend AI core supports capture-to-feedback processing: camera input, MediaPipe landmark detection, angle/feature derivation, temporal smoothing, exercise state logic, rep counting, and scoring. Key orchestration and boundaries are `Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py`, `Ai_Fitness_Tracker/backend/app/core_ai/pose/pose_detector.py`, and `Ai_Fitness_Tracker/backend/app/core_ai/processing/rep_counter.py`. Exercise-specific rules reside in `Ai_Fitness_Tracker/backend/app/core_ai/exercises/`, keeping interpretable movement semantics separate from API and persistence code.

#### Personalization and AI Coaching
Personal targets and coaching combine stored user/workout context with lightweight ML and LLM-oriented coach logic. The Random Forest-related model path is represented by `Ai_Fitness_Tracker/backend/app/core_ai/personalization_model.py` and `Ai_Fitness_Tracker/backend/app/core_ai/processing/ml_models.py`; chatbot/AI endpoints are `Ai_Fitness_Tracker/backend/app/api/v1/chatbot.py` and `Ai_Fitness_Tracker/backend/app/api/v1/ai.py`. Coach implementations in `Ai_Fitness_Tracker/backend/app/core_ai/coach/` produce guidance for plans, lifestyle, or workout feedback.

#### Real-Time, External Infrastructure, and Operations
WebSockets support real-time chat and social-duel/session updates via `Ai_Fitness_Tracker/backend/app/api/v1/websockets.py` and `Ai_Fitness_Tracker/backend/app/websockets.py`, consumed by `Ai_Fitness_Tracker/frontend/src/hooks/useWebSocket.js`. PostgreSQL is the intended production datastore; Redis is an additional runtime dependency managed through `Ai_Fitness_Tracker/backend/app/core/redis.py`. Material external/model services include MediaPipe, scikit-learn/joblib model artifacts, and an LLM provider configured through backend settings rather than embedded in the frontend.

Main entry points: [`Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py`](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py) (Exercise CV pipeline), [`Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js`](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js) (Live workout UI), [`Ai_Fitness_Tracker/backend/app/api/v1/websockets.py`](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/api/v1/websockets.py) (Realtime endpoints), [`Ai_Fitness_Tracker/backend/app/db/database.py`](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/db/database.py) (SQLAlchemy data layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_react_entry["React entry &amp; routes<br/>React app<br/>[index.js]"]
  node_live_workout["Live workout UI<br/>screen<br/>[LiveWorkout.js]"]
  node_camera_view["Camera pose capture<br/>MediaPipe client<br/>[CameraView.js]"]
  node_workout_state["Workout state<br/>React context<br/>[WorkoutContext.js]"]
  node_websocket_hook["WebSocket client<br/>React hook<br/>[useWebSocket.js]"]
end

subgraph group_api["FastAPI Backend"]
  node_fastapi_app["FastAPI application<br/>API entrypoint<br/>[main.py]"]
  node_v1_routers["Versioned API routers<br/>HTTP endpoints"]
  node_auth_policy["Auth &amp; request policy<br/>JWT security<br/>[dependencies.py]"]
  node_domain_services["Workout &amp; activity services<br/>service layer<br/>[workout_service.py]"]
end

subgraph group_ai["AI Processing"]
  node_cv_pipeline["Exercise CV pipeline<br/>AI orchestrator<br/>[pipeline.py]"]
  node_pose_detection["Pose detection<br/>MediaPipe adapter<br/>[pose_detector.py]"]
  node_rep_counting["Rep counting &amp; scoring<br/>motion processing<br/>[rep_counter.py]"]
  node_exercise_rules["Exercise rules<br/>movement semantics"]
  node_personalization["Personalization model<br/>ML model"]
  node_coach["AI coach<br/>guidance engine"]
end

subgraph group_data["Data &amp; Realtime"]
  node_websocket_server["Realtime endpoints<br/>WebSocket API<br/>[websockets.py]"]
  node_repositories["Workout repository<br/>repository layer<br/>[workout_repo.py]"]
  node_database_layer[("SQLAlchemy data layer<br/>async ORM<br/>[database.py]")]
  node_postgres[("PostgreSQL<br/>production datastore")]
  node_redis[("Redis<br/>runtime cache<br/>[redis.py]")]
end

node_llm_provider{{"LLM provider<br/>external AI service"}}

node_react_entry -->|"renders"| node_live_workout
node_live_workout -->|"uses"| node_camera_view
node_live_workout -->|"updates"| node_workout_state
node_camera_view -->|"submits pose/workout input"| node_cv_pipeline
node_react_entry -->|"HTTP API"| node_v1_routers
node_websocket_hook -->|"WebSocket"| node_websocket_server
node_fastapi_app -->|"mounts"| node_v1_routers
node_fastapi_app -->|"hosts"| node_websocket_server
node_v1_routers -->|"enforces"| node_auth_policy
node_v1_routers -->|"delegates"| node_domain_services
node_v1_routers -->|"invokes AI feedback"| node_cv_pipeline
node_v1_routers -->|"requests coaching"| node_coach
node_domain_services -->|"persists via"| node_repositories
node_repositories -->|"uses"| node_database_layer
node_database_layer -->|"stores relational data"| node_postgres
node_websocket_server -->|"uses runtime state"| node_redis
node_cv_pipeline -->|"detects landmarks"| node_pose_detection
node_cv_pipeline -->|"derives reps and score"| node_rep_counting
node_rep_counting -->|"applies rules"| node_exercise_rules
node_coach -->|"uses user targets"| node_personalization
node_coach -->|"generates guidance"| node_llm_provider
node_personalization -->|"uses workout context"| node_database_layer

click node_react_entry "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/index.js"
click node_live_workout "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js"
click node_camera_view "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/components/CameraView.js"
click node_workout_state "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/contexts/WorkoutContext.js"
click node_websocket_hook "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/hooks/useWebSocket.js"
click node_fastapi_app "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/main.py"
click node_auth_policy "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/api/dependencies.py"
click node_domain_services "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/services/workout_service.py"
click node_websocket_server "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/api/v1/websockets.py"
click node_repositories "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/db/repositories/workout_repo.py"
click node_database_layer "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/db/database.py"
click node_redis "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core/redis.py"
click node_cv_pipeline "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py"
click node_pose_detection "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/pose/pose_detector.py"
click node_rep_counting "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/processing/rep_counter.py"
click node_personalization "https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/personalization_model.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_react_entry,node_live_workout,node_camera_view,node_workout_state,node_websocket_hook toneBlue
class node_fastapi_app,node_v1_routers,node_auth_policy,node_domain_services toneAmber
class node_cv_pipeline,node_pose_detection,node_rep_counting,node_exercise_rules,node_personalization,node_coach toneMint
class node_websocket_server,node_repositories,node_database_layer,node_postgres,node_redis toneRose
class node_llm_provider toneNeutral
```

## Components

### React Client

- [React entry & routes](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/index.js): React app · `Ai_Fitness_Tracker/frontend/src/index.js`
- [Live workout UI](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js): screen · `Ai_Fitness_Tracker/frontend/src/screens/LiveWorkout.js`
- [Camera pose capture](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/components/CameraView.js): MediaPipe client · Processes browser camera input locally. · `Ai_Fitness_Tracker/frontend/src/components/CameraView.js`
- [Workout state](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/contexts/WorkoutContext.js): React context · `Ai_Fitness_Tracker/frontend/src/contexts/WorkoutContext.js`
- [WebSocket client](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/frontend/src/hooks/useWebSocket.js): React hook · `Ai_Fitness_Tracker/frontend/src/hooks/useWebSocket.js`

### FastAPI Backend

- [FastAPI application](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/main.py): API entrypoint · `Ai_Fitness_Tracker/backend/app/main.py`
- **Versioned API routers**: HTTP endpoints · Auth, workouts, plans, dashboards, social, AI, chatbot, hydration, and voice APIs.
- [Auth & request policy](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/api/dependencies.py): JWT security · Centralizes authentication dependencies, security, and middleware. · `Ai_Fitness_Tracker/backend/app/api/dependencies.py`
- [Workout & activity services](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/services/workout_service.py): service layer · `Ai_Fitness_Tracker/backend/app/services/workout_service.py`

### AI Processing

- [Exercise CV pipeline](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py): AI orchestrator · Runs pose analysis through feedback scoring. · `Ai_Fitness_Tracker/backend/app/core_ai/pipeline.py`
- [Pose detection](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/pose/pose_detector.py): MediaPipe adapter · `Ai_Fitness_Tracker/backend/app/core_ai/pose/pose_detector.py`
- [Rep counting & scoring](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/processing/rep_counter.py): motion processing · `Ai_Fitness_Tracker/backend/app/core_ai/processing/rep_counter.py`
- **Exercise rules**: movement semantics
- [Personalization model](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core_ai/personalization_model.py): ML model · Random Forest-related personalization and model loading. · `Ai_Fitness_Tracker/backend/app/core_ai/personalization_model.py`
- **AI coach**: guidance engine · Produces plan, lifestyle, and workout guidance.

### Data & Realtime

- [Realtime endpoints](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/api/v1/websockets.py): WebSocket API · Chat and social-duel/session updates. · `Ai_Fitness_Tracker/backend/app/api/v1/websockets.py`
- [Workout repository](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/db/repositories/workout_repo.py): repository layer · `Ai_Fitness_Tracker/backend/app/db/repositories/workout_repo.py`
- [SQLAlchemy data layer](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/db/database.py): async ORM · Models and async database setup. · `Ai_Fitness_Tracker/backend/app/db/database.py`
- **PostgreSQL**: production datastore
- [Redis](https://github.com/kakumanu-harshitha/fitvision-ai/blob/main/Ai_Fitness_Tracker/backend/app/core/redis.py): runtime cache · `Ai_Fitness_Tracker/backend/app/core/redis.py`

### Other components

- **LLM provider**: external AI service

## Connections

- React entry & routes → Live workout UI: renders
- Live workout UI → Camera pose capture: uses
- Live workout UI → Workout state: updates
- Camera pose capture → Exercise CV pipeline: submits pose/workout input
- React entry & routes → Versioned API routers: HTTP API
- WebSocket client → Realtime endpoints: WebSocket
- FastAPI application → Versioned API routers: mounts
- FastAPI application → Realtime endpoints: hosts
- Versioned API routers → Auth & request policy: enforces
- Versioned API routers → Workout & activity services: delegates
- Versioned API routers → Exercise CV pipeline: invokes AI feedback
- Versioned API routers → AI coach: requests coaching
- Workout & activity services → Workout repository: persists via
- Workout repository → SQLAlchemy data layer: uses
- SQLAlchemy data layer → PostgreSQL: stores relational data
- Realtime endpoints → Redis: uses runtime state
- Exercise CV pipeline → Pose detection: detects landmarks
- Exercise CV pipeline → Rep counting & scoring: derives reps and score
- Rep counting & scoring → Exercise rules: applies rules
- AI coach → Personalization model: uses user targets
- AI coach → LLM provider: generates guidance
- Personalization model → SQLAlchemy data layer: uses workout context