# moosa-natiezen/southasianfitness_saas architecture

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

- Interactive diagram: https://gitdiagram.com/moosa-natiezen/southasianfitness_saas
- Repository: https://github.com/moosa-natiezen/southasianfitness_saas

## Overview

South Asian Fitness is a Desi-focused nutrition and fitness planning platform. The main user journey runs from signup and onboarding through personalized nutrition targets and meal-plan generation to dashboard tracking; users can also request AI workout guidance and record progress. The backend exposes these capabilities through FastAPI, with PostgreSQL-backed user, food, plan, and progress data. Meal planning has both a deterministic optimizer and an AI generation path, while AI chat routes requests to specialist workers. The README documents these capabilities; unsampled route and service implementations limit some call-level detail.

Main entry points: [`frontend/app`](https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/frontend/app) (Next.js app), [`frontend/lib/api.ts`](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/lib/api.ts) (API client), [`backend/app/db/session.py`](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/db/session.py) (Database session), [`backend/app/api/router.py`](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/router.py) (REST routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Next.js app"]
  node_onboarding_ui["Onboarding wizard"]
  node_meal_ui["Meal plan views<br/>[meal-plan-view.tsx]"]
  node_meal_stream["Meal stream hook"]
  node_workout_ui["Workout generator"]
  node_dashboard["Dashboard views"]
  node_api_client["API client<br/>[api.ts]"]
  node_enqueue["Meal plan enqueue<br/>[route.ts]"]
  node_task["Generation task"]
end

subgraph group_api["API and identity"]
  node_api_router["FastAPI app<br/>[main.py]"]
  node_routes["REST routes<br/>[router.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_service["Auth and onboarding<br/>[auth_service.py]"]
  node_meal_routes["Meal plan routes<br/>[meal_plans.py]"]
  node_ai_routes["AI routes<br/>[ai.py]"]
end

subgraph group_planning["Nutrition and coaching"]
  node_nutrition["Nutrition services"]
  node_optimizer["Meal optimizer<br/>[meal_optimizer.py]"]
  node_ai_service["AI generation<br/>[ai_service.py]"]
  node_agent_orch["Intent orchestrator<br/>[orchestrator.py]"]
  node_nutrition_worker["Nutrition worker"]
  node_workout_worker["Workout worker<br/>[workout_worker.py]"]
  node_context["AI user context"]
end

subgraph group_data["Product data"]
  node_food_service["Food services<br/>[food_service.py]"]
  node_progress_service["Progress services"]
  node_db_session["Database session<br/>[session.py]"]
  node_models["Domain models"]
  node_database[("PostgreSQL")]
end

node_user(("Member"))
node_openai{{"OpenAI"}}
node_trigger["Trigger.dev"]

node_user -->|"uses"| node_webapp
node_webapp -->|"presents"| node_onboarding_ui
node_webapp -->|"presents"| node_meal_ui
node_webapp -->|"presents"| node_dashboard
node_webapp -->|"presents"| node_workout_ui
node_onboarding_ui -->|"submits profile"| node_api_client
node_meal_ui -->|"starts generation"| node_meal_stream
node_meal_stream -->|"requests data"| node_api_client
node_workout_ui -->|"requests coaching"| node_api_client
node_dashboard -->|"loads views"| node_api_client
node_api_client -->|"HTTP requests"| node_api_router
node_api_router -->|"dispatches"| node_routes
node_routes -->|"dispatches"| node_auth_routes
node_routes -->|"dispatches"| node_meal_routes
node_routes -->|"dispatches"| node_ai_routes
node_auth_routes -->|"calls"| node_auth_service
node_meal_routes -->|"uses"| node_optimizer
node_meal_routes -->|"uses"| node_ai_service
node_ai_routes -->|"routes intent"| node_agent_orch
node_agent_orch -->|"dispatches"| node_nutrition_worker
node_agent_orch -->|"dispatches"| node_workout_worker
node_nutrition_worker -->|"generates with"| node_openai
node_workout_worker -->|"generates with"| node_openai
node_ai_service -->|"generates with"| node_openai
node_nutrition_worker -->|"uses profile context"| node_context
node_workout_worker -->|"uses profile context"| node_context
node_nutrition -->|"uses food data"| node_food_service
node_progress_service -->|"queries and updates"| node_db_session
node_auth_service -->|"queries and updates"| node_db_session
node_context -->|"loads profile"| node_db_session
node_food_service -->|"queries foods"| node_db_session
node_optimizer -->|"filters foods"| node_food_service
node_db_session -->|"connects"| node_database
node_models -->|"maps domain data"| node_database
node_meal_stream -.->|"optional background request"| node_enqueue
node_enqueue -.->|"enqueues task"| node_trigger
node_trigger -.->|"runs"| node_task
node_task -.->|"forwards authenticated request"| node_api_router

click node_webapp "https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/frontend/app"
click node_onboarding_ui "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/onboarding/onboarding-wizard.tsx"
click node_meal_ui "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/meal-plan/meal-plan-view.tsx"
click node_meal_stream "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/hooks/use-meal-plan-stream.ts"
click node_workout_ui "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/ai/ai-workout-generator.tsx"
click node_dashboard "https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/frontend/app/dashboard"
click node_api_client "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/lib/api.ts"
click node_api_router "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/main.py"
click node_routes "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/router.py"
click node_auth_routes "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/auth.py"
click node_auth_service "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/auth_service.py"
click node_meal_routes "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/meal_plans.py"
click node_ai_routes "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/ai.py"
click node_nutrition "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/nutrition_service.py"
click node_optimizer "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/meal_optimizer.py"
click node_ai_service "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/ai_service.py"
click node_agent_orch "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/orchestrator.py"
click node_nutrition_worker "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/nutrition_worker.py"
click node_workout_worker "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/workout_worker.py"
click node_context "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/ai_context_service.py"
click node_food_service "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/food_service.py"
click node_progress_service "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/progress_service.py"
click node_db_session "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/db/session.py"
click node_models "https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/backend/app/models"
click node_database "https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/backend/app/db"
click node_enqueue "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/app/api/meal-plans/enqueue/route.ts"
click node_task "https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/trigger/generate-meal-plan.ts"

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_onboarding_ui,node_meal_ui,node_meal_stream,node_workout_ui,node_dashboard,node_api_client,node_enqueue,node_task toneBlue
class node_api_router,node_routes,node_auth_routes,node_auth_service,node_meal_routes,node_ai_routes toneAmber
class node_nutrition,node_optimizer,node_ai_service,node_agent_orch,node_nutrition_worker,node_workout_worker,node_context toneMint
class node_food_service,node_progress_service,node_db_session,node_models,node_database toneRose
class node_user,node_openai,node_trigger toneIndigo
```

## Components

### Web experience

- [Next.js app](https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/frontend/app): `frontend/app`
- [Onboarding wizard](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/onboarding/onboarding-wizard.tsx): `frontend/components/onboarding/onboarding-wizard.tsx`
- [Meal plan views](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/meal-plan/meal-plan-view.tsx): `frontend/components/meal-plan/meal-plan-view.tsx`
- [Meal stream hook](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/hooks/use-meal-plan-stream.ts): `frontend/hooks/use-meal-plan-stream.ts`
- [Workout generator](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/components/ai/ai-workout-generator.tsx): `frontend/components/ai/ai-workout-generator.tsx`
- [Dashboard views](https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/frontend/app/dashboard): `frontend/app/dashboard`
- [API client](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Meal plan enqueue](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/app/api/meal-plans/enqueue/route.ts): `frontend/app/api/meal-plans/enqueue/route.ts`
- [Generation task](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/frontend/trigger/generate-meal-plan.ts): `frontend/trigger/generate-meal-plan.ts`

### API and identity

- [FastAPI app](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/main.py): `backend/app/main.py`
- [REST routes](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication routes](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Auth and onboarding](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Meal plan routes](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/meal_plans.py): `backend/app/api/routes/meal_plans.py`
- [AI routes](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/api/routes/ai.py): `backend/app/api/routes/ai.py`

### Nutrition and coaching

- [Nutrition services](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/nutrition_service.py): `backend/app/services/nutrition_service.py`
- [Meal optimizer](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/meal_optimizer.py): `backend/app/services/meal_optimizer.py`
- [AI generation](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Intent orchestrator](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/orchestrator.py): `backend/app/services/agents/orchestrator.py`
- [Nutrition worker](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/nutrition_worker.py): `backend/app/services/agents/nutrition_worker.py`
- [Workout worker](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/agents/workout_worker.py): `backend/app/services/agents/workout_worker.py`
- [AI user context](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/ai_context_service.py): `backend/app/services/ai_context_service.py`

### Product data

- [Food services](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/food_service.py): `backend/app/services/food_service.py`
- [Progress services](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/services/progress_service.py): `backend/app/services/progress_service.py`
- [Database session](https://github.com/moosa-natiezen/southasianfitness_saas/blob/master/backend/app/db/session.py): `backend/app/db/session.py`
- [Domain models](https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/backend/app/models): `backend/app/models`
- [PostgreSQL](https://github.com/moosa-natiezen/southasianfitness_saas/tree/master/backend/app/db): `backend/app/db`

### Other components

- **Member**
- **OpenAI**
- **Trigger.dev**

## Connections

- Member → Next.js app: uses
- Next.js app → Onboarding wizard: presents
- Next.js app → Meal plan views: presents
- Next.js app → Dashboard views: presents
- Next.js app → Workout generator: presents
- Onboarding wizard → API client: submits profile
- Meal plan views → Meal stream hook: starts generation
- Meal stream hook → API client: requests data
- Workout generator → API client: requests coaching
- Dashboard views → API client: loads views
- API client → FastAPI app: HTTP requests
- FastAPI app → REST routes: dispatches
- REST routes → Authentication routes: dispatches
- REST routes → Meal plan routes: dispatches
- REST routes → AI routes: dispatches
- Authentication routes → Auth and onboarding: calls
- Meal plan routes → Meal optimizer: uses
- Meal plan routes → AI generation: uses
- AI routes → Intent orchestrator: routes intent
- Intent orchestrator → Nutrition worker: dispatches
- Intent orchestrator → Workout worker: dispatches
- Nutrition worker → OpenAI: generates with
- Workout worker → OpenAI: generates with
- AI generation → OpenAI: generates with
- Nutrition worker → AI user context: uses profile context
- Workout worker → AI user context: uses profile context
- Nutrition services → Food services: uses food data
- Progress services → Database session: queries and updates
- Auth and onboarding → Database session: queries and updates
- AI user context → Database session: loads profile
- Food services → Database session: queries foods
- Meal optimizer → Food services: filters foods
- Database session → PostgreSQL: connects
- Domain models → PostgreSQL: maps domain data
- Meal stream hook → Meal plan enqueue: optional background request
- Meal plan enqueue → Trigger.dev: enqueues task
- Trigger.dev → Generation task: runs
- Generation task → FastAPI app: forwards authenticated request