# vishal41643-stack/fitnation-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vishal41643-stack/fitnation-ai
- Repository: https://github.com/vishal41643-stack/fitnation-ai

## Overview

FitNation AI is a fitness platform whose main user journey runs from profile and fitness assessment through workout planning and exercise tracking, with activity, nutrition, coaching, and community features around that journey. The React client sends requests through its API service to the Express application and domain routes; those routes use PostgreSQL and, for AI features, a provider abstraction. The README documents additional capabilities, including notifications, group podiums, and reward ledgers. Route-to-provider and route-to-database links are based on sampled imports and calls; unsampled feature wiring is not inferred.

Main entry points: [`backend/src/app.js`](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/app.js) (API Gateway), [`backend/src/config/db.js`](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/config/db.js) (Database Access), [`backend/src/modules/workouts/workouts.routes.js`](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/workouts/workouts.routes.js) (Workout Plans And Sessions), [`backend/src/modules/users/users.routes.js`](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/users/users.routes.js) (Profiles And Assessment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_webapp["React Application<br/>[App.jsx]"]
  node_webpages["Fitness Screens"]
  node_webapi["API Client<br/>[api.js]"]
end

subgraph group_identity["Identity And Platform"]
  node_backend["API Gateway<br/>[app.js]"]
  node_users["Profiles And Assessment<br/>[users.routes.js]"]
  node_auth["Authentication Context<br/>[auth.js]"]
end

subgraph group_training["Training And Health"]
  node_workouts["Workout Plans And Sessions<br/>[workouts.routes.js]"]
  node_formroutes["Form Check API"]
  node_formengine["Form Analysis Engine<br/>[engine.js]"]
  node_kinematics["Pose Kinematics<br/>[kinematics.js]"]
  node_activity["Activity Trends<br/>[activity.routes.js]"]
  node_nutrition["Nutrition Logs"]
  node_coach["AI Coach And Food Parser<br/>[aiCoach.routes.js]"]
end

subgraph group_community["Community And Rewards"]
  node_challenges["Challenge Progress"]
  node_gamification["Points And Achievements"]
  node_leaderboard["Leaderboards"]
  node_groups["Community Groups<br/>[groups.routes.js]"]
  node_notifications["Notifications"]
end

subgraph group_integrations["Data And Providers"]
  node_dbaccess["Database Access<br/>[db.js]"]
  node_postgres[("PostgreSQL")]
  node_aiservice["AI Provider Service<br/>[index.js]"]
  node_aiprovider["OpenAI Or Mock<br/>[AIProvider.js]"]
  node_firebase["Firebase Auth"]
  node_fcm["Firebase Messaging"]
end

node_athlete(("Athlete"))

node_athlete -->|"uses"| node_webapp
node_webapp -->|"renders"| node_webpages
node_webpages -->|"requests data"| node_webapi
node_webapi -->|"sends API requests"| node_backend
node_backend -->|"mounts routes"| node_users
node_backend -->|"mounts routes"| node_workouts
node_backend -->|"mounts routes"| node_formroutes
node_backend -->|"mounts routes"| node_activity
node_backend -->|"mounts routes"| node_nutrition
node_backend -->|"mounts routes"| node_coach
node_backend -->|"mounts routes"| node_challenges
node_backend -->|"mounts routes"| node_gamification
node_backend -->|"mounts routes"| node_leaderboard
node_backend -->|"mounts routes"| node_groups
node_backend -->|"mounts routes"| node_notifications
node_users -->|"authenticates"| node_auth
node_workouts -->|"authenticates"| node_auth
node_formroutes -->|"analyzes pose"| node_formengine
node_formengine -->|"calculates geometry"| node_kinematics
node_workouts -->|"generates plans"| node_aiservice
node_coach -->|"requests AI"| node_aiservice
node_aiservice -->|"dispatches prompts"| node_aiprovider
node_users -->|"queries"| node_dbaccess
node_workouts -->|"queries"| node_dbaccess
node_activity -->|"queries"| node_dbaccess
node_nutrition -->|"queries"| node_dbaccess
node_coach -->|"reads and writes"| node_dbaccess
node_challenges -->|"records progress"| node_dbaccess
node_gamification -->|"reads and awards"| node_dbaccess
node_leaderboard -->|"queries rankings"| node_dbaccess
node_groups -->|"manages membership"| node_dbaccess
node_notifications -->|"stores tokens"| node_dbaccess
node_dbaccess -->|"reads and writes"| node_postgres
node_auth -->|"verifies identity"| node_firebase
node_notifications -.->|"push integration"| node_fcm

click node_webapp "https://github.com/vishal41643-stack/fitnation-ai/blob/main/apps/web/src/App.jsx"
click node_webpages "https://github.com/vishal41643-stack/fitnation-ai/tree/main/apps/web/src/pages"
click node_webapi "https://github.com/vishal41643-stack/fitnation-ai/blob/main/apps/web/src/services/api.js"
click node_backend "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/app.js"
click node_users "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/users/users.routes.js"
click node_auth "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/middleware/auth.js"
click node_workouts "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/workouts/workouts.routes.js"
click node_formroutes "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/formCheck.routes.js"
click node_formengine "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/engine.js"
click node_kinematics "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/kinematics.js"
click node_activity "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/activity/activity.routes.js"
click node_nutrition "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/nutrition/nutrition.routes.js"
click node_coach "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/ai-coach/aiCoach.routes.js"
click node_challenges "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/challenges/challenges.routes.js"
click node_gamification "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/gamification/gamification.routes.js"
click node_leaderboard "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/leaderboard/leaderboard.routes.js"
click node_groups "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/groups/groups.routes.js"
click node_notifications "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/notifications/notifications.routes.js"
click node_dbaccess "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/config/db.js"
click node_aiservice "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/services/ai/index.js"
click node_aiprovider "https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/services/ai/AIProvider.js"

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_webapp,node_webpages,node_webapi toneBlue
class node_backend,node_users,node_auth toneAmber
class node_workouts,node_formroutes,node_formengine,node_kinematics,node_activity,node_nutrition,node_coach toneMint
class node_challenges,node_gamification,node_leaderboard,node_groups,node_notifications toneRose
class node_dbaccess,node_postgres,node_aiservice,node_aiprovider,node_firebase,node_fcm,node_athlete toneIndigo
```

## Components

### Web Client

- [React Application](https://github.com/vishal41643-stack/fitnation-ai/blob/main/apps/web/src/App.jsx): `apps/web/src/App.jsx`
- [Fitness Screens](https://github.com/vishal41643-stack/fitnation-ai/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [API Client](https://github.com/vishal41643-stack/fitnation-ai/blob/main/apps/web/src/services/api.js): `apps/web/src/services/api.js`

### Identity And Platform

- [API Gateway](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/app.js): `backend/src/app.js`
- [Profiles And Assessment](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/users/users.routes.js): `backend/src/modules/users/users.routes.js`
- [Authentication Context](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`

### Training And Health

- [Workout Plans And Sessions](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/workouts/workouts.routes.js): `backend/src/modules/workouts/workouts.routes.js`
- [Form Check API](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/formCheck.routes.js): `backend/src/modules/exercise-form/formCheck.routes.js`
- [Form Analysis Engine](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/engine.js): `backend/src/modules/exercise-form/engine.js`
- [Pose Kinematics](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/exercise-form/kinematics.js): `backend/src/modules/exercise-form/kinematics.js`
- [Activity Trends](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/activity/activity.routes.js): `backend/src/modules/activity/activity.routes.js`
- [Nutrition Logs](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/nutrition/nutrition.routes.js): `backend/src/modules/nutrition/nutrition.routes.js`
- [AI Coach And Food Parser](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/ai-coach/aiCoach.routes.js): `backend/src/modules/ai-coach/aiCoach.routes.js`

### Community And Rewards

- [Challenge Progress](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/challenges/challenges.routes.js): `backend/src/modules/challenges/challenges.routes.js`
- [Points And Achievements](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/gamification/gamification.routes.js): `backend/src/modules/gamification/gamification.routes.js`
- [Leaderboards](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/leaderboard/leaderboard.routes.js): `backend/src/modules/leaderboard/leaderboard.routes.js`
- [Community Groups](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/groups/groups.routes.js): `backend/src/modules/groups/groups.routes.js`
- [Notifications](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/modules/notifications/notifications.routes.js): `backend/src/modules/notifications/notifications.routes.js`

### Data And Providers

- [Database Access](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/config/db.js): `backend/src/config/db.js`
- **PostgreSQL**
- [AI Provider Service](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/services/ai/index.js): `backend/src/services/ai/index.js`
- [OpenAI Or Mock](https://github.com/vishal41643-stack/fitnation-ai/blob/main/backend/src/services/ai/AIProvider.js): `backend/src/services/ai/AIProvider.js`
- **Firebase Auth**
- **Firebase Messaging**

### Other components

- **Athlete**

## Connections

- Athlete → React Application: uses
- React Application → Fitness Screens: renders
- Fitness Screens → API Client: requests data
- API Client → API Gateway: sends API requests
- API Gateway → Profiles And Assessment: mounts routes
- API Gateway → Workout Plans And Sessions: mounts routes
- API Gateway → Form Check API: mounts routes
- API Gateway → Activity Trends: mounts routes
- API Gateway → Nutrition Logs: mounts routes
- API Gateway → AI Coach And Food Parser: mounts routes
- API Gateway → Challenge Progress: mounts routes
- API Gateway → Points And Achievements: mounts routes
- API Gateway → Leaderboards: mounts routes
- API Gateway → Community Groups: mounts routes
- API Gateway → Notifications: mounts routes
- Profiles And Assessment → Authentication Context: authenticates
- Workout Plans And Sessions → Authentication Context: authenticates
- Form Check API → Form Analysis Engine: analyzes pose
- Form Analysis Engine → Pose Kinematics: calculates geometry
- Workout Plans And Sessions → AI Provider Service: generates plans
- AI Coach And Food Parser → AI Provider Service: requests AI
- AI Provider Service → OpenAI Or Mock: dispatches prompts
- Profiles And Assessment → Database Access: queries
- Workout Plans And Sessions → Database Access: queries
- Activity Trends → Database Access: queries
- Nutrition Logs → Database Access: queries
- AI Coach And Food Parser → Database Access: reads and writes
- Challenge Progress → Database Access: records progress
- Points And Achievements → Database Access: reads and awards
- Leaderboards → Database Access: queries rankings
- Community Groups → Database Access: manages membership
- Notifications → Database Access: stores tokens
- Database Access → PostgreSQL: reads and writes
- Authentication Context → Firebase Auth: verifies identity
- Notifications → Firebase Messaging: push integration