# jagtap13/multi-coach-ai-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/jagtap13/multi-coach-ai-trainer
- Repository: https://github.com/jagtap13/multi-coach-ai-trainer

## Overview

This is a multi-coach AI fitness platform. Users authenticate, choose a coach, and send profile-aware questions through chat; the backend retrieves coach-scoped fitness knowledge, generates and safety-checks an answer, then may translate it and attach exercise videos before saving the conversation. The product also supports account/profile management, progress tracking, saved-plan PDF export, feedback, and knowledge-base administration. Edges reflect shown imports/calls or README-documented behavior; several secondary route and frontend details are represented at subsystem level because their implementation was not excerpted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/App.jsx) (App shell), [`backend/app/core/database.py`](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/core/database.py) (Database session), [`backend/app/main.py`](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/main.py) (FastAPI routes), [`backend/app/services/rag_pipeline.py`](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/rag_pipeline.py) (RAG and safety pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_app["App shell<br/>[App.jsx]"]
  node_chat_ui["Chat interface<br/>[ChatWindow.jsx]"]
  node_history_ui["Chat history UI<br/>[HistoryPanel.jsx]"]
  node_video_ui["Video cards<br/>[VideoCards.jsx]"]
  node_auth_ui["Auth form<br/>[AuthForm.jsx]"]
  node_profile_ui["Profile form<br/>[ProfileForm.jsx]"]
  node_progress_ui["Progress tracker"]
  node_plans_ui["Plan viewer<br/>[PlanViewer.jsx]"]
  node_feedback_ui["Feedback dashboard"]
  node_kb_ui["KB admin UI"]
end

subgraph group_coaching["Coaching pipeline"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_rag["RAG and safety pipeline<br/>[rag_pipeline.py]"]
  node_prompts["Coach prompts<br/>[coach_prompts.py]"]
  node_ollama["Ollama inference<br/>[ollama_client.py]"]
end

subgraph group_accounts["Accounts and tracking"]
  node_auth_routes["Auth routes<br/>[auth_routes.py]"]
  node_email["Reset email<br/>[email_utils.py]"]
  node_profile_routes["Profile routes<br/>[profile_routes.py]"]
  node_progress_routes["Progress routes<br/>[progress_routes.py]"]
  node_plan_routes["Workout plan routes"]
  node_pdf["PDF export<br/>[plan_pdf.py]"]
  node_feedback_routes["Feedback routes<br/>[feedback_routes.py]"]
end

subgraph group_knowledge["Knowledge and media"]
  node_retriever["Coach-scoped retriever<br/>[retriever.py]"]
  node_ingest["Knowledge ingestion<br/>[ingest.py]"]
  node_youtube["Video lookup<br/>[youtube_service.py]"]
  node_nutrition_videos["Nutrition videos"]
  node_kb_routes["KB admin routes<br/>[kb_admin_routes.py]"]
end

subgraph group_persistence["Persistence"]
  node_database["Database session<br/>[database.py]"]
  node_chat_model["Chat history model<br/>[chat_history.py]"]
  node_user_model["User model<br/>[user.py]"]
  node_video_model["Exercise video model<br/>[exercise_video.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_chat_ui
node_app -->|"renders"| node_auth_ui
node_app -->|"renders"| node_profile_ui
node_app -->|"renders"| node_progress_ui
node_app -->|"renders"| node_plans_ui
node_app -->|"renders"| node_feedback_ui
node_app -->|"renders"| node_kb_ui
node_chat_ui -->|"requests chat"| node_api
node_chat_ui -->|"renders"| node_history_ui
node_chat_ui -->|"renders"| node_video_ui
node_api -->|"requests answer"| node_rag
node_rag -->|"retrieves chunks"| node_retriever
node_rag -->|"gets persona"| node_prompts
node_rag -->|"generates text"| node_ollama
node_api -->|"looks up videos"| node_youtube
node_api -->|"gets nutrition videos"| node_nutrition_videos
node_ingest -.->|"builds knowledge index"| node_retriever
node_auth_ui -->|"authenticates"| node_auth_routes
node_auth_routes -->|"sends reset email"| node_email
node_app -.->|"loads profile"| node_profile_routes
node_app -.->|"manages progress"| node_progress_routes
node_app -.->|"manages plans"| node_plan_routes
node_plan_routes -->|"structures plan"| node_rag
node_plan_routes -->|"builds PDF"| node_pdf
node_app -.->|"manages feedback"| node_feedback_routes
node_app -.->|"administers knowledge"| node_kb_routes
node_api -->|"saves conversations"| node_chat_model
node_auth_routes -->|"reads and writes users"| node_user_model
node_youtube -->|"caches videos"| node_video_model
node_database -->|"connects"| node_postgres
node_chat_model -->|"uses base"| node_database
node_user_model -->|"uses base"| node_database
node_progress_routes -->|"queries entries"| node_database
node_plan_routes -->|"stores plans"| node_database
node_feedback_routes -->|"stores feedback"| node_database
node_kb_routes -.->|"checks admin"| node_user_model

click node_app "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/App.jsx"
click node_chat_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ChatWindow.jsx"
click node_history_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/HistoryPanel.jsx"
click node_video_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/VideoCards.jsx"
click node_auth_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/AuthForm.jsx"
click node_profile_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ProfileForm.jsx"
click node_progress_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ProgressTracker.jsx"
click node_plans_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/PlanViewer.jsx"
click node_feedback_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/FeedbackDashboard.jsx"
click node_kb_ui "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/KnowledgeBaseAdmin.jsx"
click node_api "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/main.py"
click node_rag "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/rag_pipeline.py"
click node_prompts "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/coaches/coach_prompts.py"
click node_retriever "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/rag/retriever.py"
click node_ingest "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/rag/ingest.py"
click node_ollama "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/llm/ollama_client.py"
click node_youtube "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/youtube_service.py"
click node_nutrition_videos "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/nutrition_videos.py"
click node_auth_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/auth_routes.py"
click node_email "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/email_utils.py"
click node_profile_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/profile_routes.py"
click node_progress_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/progress_routes.py"
click node_plan_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/workout_plan_routes.py"
click node_pdf "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/plan_pdf.py"
click node_feedback_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/feedback_routes.py"
click node_kb_routes "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/kb_admin_routes.py"
click node_database "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/core/database.py"
click node_chat_model "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/chat_history.py"
click node_user_model "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/user.py"
click node_video_model "https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/exercise_video.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_app,node_chat_ui,node_history_ui,node_video_ui,node_auth_ui,node_profile_ui,node_progress_ui,node_plans_ui,node_feedback_ui,node_kb_ui,node_user toneBlue
class node_api,node_rag,node_prompts,node_ollama,node_postgres toneAmber
class node_auth_routes,node_email,node_profile_routes,node_progress_routes,node_plan_routes,node_pdf,node_feedback_routes toneMint
class node_retriever,node_ingest,node_youtube,node_nutrition_videos,node_kb_routes toneRose
class node_database,node_chat_model,node_user_model,node_video_model toneIndigo
```

## Components

### Web experience

- [App shell](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ChatWindow.jsx): `frontend/src/ChatWindow.jsx`
- [Chat history UI](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/HistoryPanel.jsx): `frontend/src/HistoryPanel.jsx`
- [Video cards](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/VideoCards.jsx): `frontend/src/VideoCards.jsx`
- [Auth form](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/AuthForm.jsx): `frontend/src/AuthForm.jsx`
- [Profile form](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ProfileForm.jsx): `frontend/src/ProfileForm.jsx`
- [Progress tracker](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/ProgressTracker.jsx): `frontend/src/ProgressTracker.jsx`
- [Plan viewer](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/PlanViewer.jsx): `frontend/src/PlanViewer.jsx`
- [Feedback dashboard](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/FeedbackDashboard.jsx): `frontend/src/FeedbackDashboard.jsx`
- [KB admin UI](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/frontend/src/KnowledgeBaseAdmin.jsx): `frontend/src/KnowledgeBaseAdmin.jsx`

### Coaching pipeline

- [FastAPI routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/main.py): `backend/app/main.py`
- [RAG and safety pipeline](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/rag_pipeline.py): `backend/app/services/rag_pipeline.py`
- [Coach prompts](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/coaches/coach_prompts.py): `backend/app/coaches/coach_prompts.py`
- [Ollama inference](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/llm/ollama_client.py): `backend/app/llm/ollama_client.py`

### Accounts and tracking

- [Auth routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/auth_routes.py): `backend/app/api/auth_routes.py`
- [Reset email](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/email_utils.py): `backend/app/api/email_utils.py`
- [Profile routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/profile_routes.py): `backend/app/api/profile_routes.py`
- [Progress routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/progress_routes.py): `backend/app/api/progress_routes.py`
- [Workout plan routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/workout_plan_routes.py): `backend/app/api/workout_plan_routes.py`
- [PDF export](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/plan_pdf.py): `backend/app/services/plan_pdf.py`
- [Feedback routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/feedback_routes.py): `backend/app/api/feedback_routes.py`

### Knowledge and media

- [Coach-scoped retriever](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Knowledge ingestion](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/rag/ingest.py): `backend/app/rag/ingest.py`
- [Video lookup](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/youtube_service.py): `backend/app/services/youtube_service.py`
- [Nutrition videos](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/services/nutrition_videos.py): `backend/app/services/nutrition_videos.py`
- [KB admin routes](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/api/kb_admin_routes.py): `backend/app/api/kb_admin_routes.py`

### Persistence

- [Database session](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/core/database.py): `backend/app/core/database.py`
- [Chat history model](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/chat_history.py): `backend/app/models/chat_history.py`
- [User model](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/user.py): `backend/app/models/user.py`
- [Exercise video model](https://github.com/jagtap13/multi-coach-ai-trainer/blob/master/backend/app/models/exercise_video.py): `backend/app/models/exercise_video.py`

### Other components

- **User**
- **PostgreSQL**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Chat interface: renders (evidence: `frontend/src/App.jsx`)
- App shell → Auth form: renders (evidence: `frontend/src/App.jsx`)
- App shell → Profile form: renders (evidence: `frontend/src/App.jsx`)
- App shell → Progress tracker: renders (evidence: `frontend/src/App.jsx`)
- App shell → Plan viewer: renders (evidence: `frontend/src/App.jsx`)
- App shell → Feedback dashboard: renders (evidence: `frontend/src/App.jsx`)
- App shell → KB admin UI: renders (evidence: `frontend/src/App.jsx`)
- Chat interface → FastAPI routes: requests chat (evidence: `README.md`)
- Chat interface → Chat history UI: renders (evidence: `frontend/src/ChatWindow.jsx`)
- Chat interface → Video cards: renders (evidence: `frontend/src/ChatWindow.jsx`)
- FastAPI routes → RAG and safety pipeline: requests answer (evidence: `backend/app/main.py`)
- RAG and safety pipeline → Coach-scoped retriever: retrieves chunks (evidence: `backend/app/services/rag_pipeline.py`)
- RAG and safety pipeline → Coach prompts: gets persona (evidence: `backend/app/services/rag_pipeline.py`)
- RAG and safety pipeline → Ollama inference: generates text (evidence: `backend/app/services/rag_pipeline.py`)
- FastAPI routes → Video lookup: looks up videos (evidence: `backend/app/main.py`)
- FastAPI routes → Nutrition videos: gets nutrition videos (evidence: `backend/app/main.py`)
- Knowledge ingestion → Coach-scoped retriever: builds knowledge index (evidence: `README.md`)
- Auth form → Auth routes: authenticates (evidence: `README.md`)
- Auth routes → Reset email: sends reset email (evidence: `backend/app/api/auth_routes.py`)
- App shell → Profile routes: loads profile
- App shell → Progress routes: manages progress
- App shell → Workout plan routes: manages plans
- Workout plan routes → RAG and safety pipeline: structures plan (evidence: `backend/app/api/workout_plan_routes.py`)
- Workout plan routes → PDF export: builds PDF (evidence: `backend/app/api/workout_plan_routes.py`)
- App shell → Feedback routes: manages feedback
- App shell → KB admin routes: administers knowledge
- FastAPI routes → Chat history model: saves conversations (evidence: `backend/app/main.py`)
- Auth routes → User model: reads and writes users (evidence: `backend/app/api/auth_routes.py`)
- Video lookup → Exercise video model: caches videos (evidence: `backend/app/services/youtube_service.py`)
- Database session → PostgreSQL: connects (evidence: `backend/app/core/database.py`)
- Chat history model → Database session: uses base (evidence: `backend/app/models/chat_history.py`)
- User model → Database session: uses base (evidence: `backend/app/models/user.py`)
- Progress routes → Database session: queries entries (evidence: `backend/app/api/progress_routes.py`)
- Workout plan routes → Database session: stores plans (evidence: `backend/app/api/workout_plan_routes.py`)
- Feedback routes → Database session: stores feedback (evidence: `backend/app/api/feedback_routes.py`)
- KB admin routes → User model: checks admin (evidence: `backend/app/api/kb_admin_routes.py`)
