# danven-ong/nusgyms architecture

> Architecture diagram of the GitHub repository danven-ong/nusgyms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danven-ong/nusgyms
- Repository: https://github.com/danven-ong/nusgyms

## Overview

NUSGyms is a full-stack workout companion for NUS gym users. A signed-in user can manage workout templates, log sessions, review history and analytics, check gym capacity, and build a schedule-aware training plan. The frontend routes users through protected pages; the backend exposes API routes, applies authentication where configured, and delegates domain work to controllers and services backed by PostgreSQL. The source excerpts establish several backend call paths, but do not show most frontend API requests or the full analytics and capacity implementations, so those links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/danven-ong/nusgyms/blob/main/frontend/src/App.tsx) (Frontend routes), [`backend/src/middleware/authMiddleware.ts`](https://github.com/danven-ong/nusgyms/blob/main/backend/src/middleware/authMiddleware.ts) (Token guard), [`backend/src/controllers/workoutTemplateController.ts`](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutTemplateController.ts) (Template handlers), [`backend/src/controllers/workoutSessionController.ts`](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutSessionController.ts) (Session handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Frontend routes<br/>[App.tsx]"]
  node_auth_pages["Account pages"]
  node_workout_pages["Workout pages"]
  node_planner_pages["Planner pages<br/>[PlannerPage.tsx]"]
end

subgraph group_identity["Accounts and settings"]
  node_auth_routes["Auth routes<br/>[authRoutes.ts]"]
  node_auth_controller["Account handlers<br/>[authController.ts]"]
  node_auth_service["Identity service<br/>[auth.ts]"]
  node_auth_guard["Token guard<br/>[authMiddleware.ts]"]
  node_settings["Account settings"]
end

subgraph group_training["Workout tracking"]
  node_template_controller["Template handlers"]
  node_session_controller["Session handlers"]
  node_workout_service["Workout service<br/>[workout.ts]"]
  node_session_service["Session service<br/>[workoutSession.ts]"]
  node_template_service["Template service<br/>[workoutTemplate.ts]"]
end

subgraph group_planning["Planning and capacity"]
  node_planner_routes["Planner routes<br/>[plannerRoutes.ts]"]
  node_planner_controller["Planner handlers"]
  node_planner_logic["Planner services"]
  node_capacity["Gym capacity<br/>[gymCapacity.ts]"]
end

subgraph group_insights["Progress and profile"]
  node_analytics["Workout analytics"]
  node_profile["Profile and weight"]
end

node_user(("Gym user"))
node_backend["API application<br/>[app.ts]"]
node_database[("PostgreSQL<br/>[index.ts]")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_auth_pages
node_app -->|"routes to"| node_workout_pages
node_app -->|"routes to"| node_planner_pages
node_app -.->|"requests"| node_backend
node_backend -->|"mounts"| node_auth_routes
node_backend -->|"mounts"| node_planner_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_routes -->|"authenticates"| node_auth_guard
node_auth_controller -->|"calls"| node_auth_service
node_auth_controller -->|"uses identity"| node_auth_guard
node_settings -->|"sends OTP"| node_auth_service
node_planner_routes -->|"dispatches"| node_planner_controller
node_planner_routes -->|"authenticates"| node_auth_guard
node_planner_controller -->|"delegates"| node_planner_logic
node_template_controller -->|"calls"| node_template_service
node_template_controller -->|"calls"| node_session_service
node_template_controller -->|"calls"| node_workout_service
node_session_controller -->|"loads template"| node_template_service
node_session_controller -->|"creates session"| node_session_service
node_session_controller -->|"stores sets"| node_workout_service
node_workout_service -->|"reads and writes"| node_database
node_session_service -->|"reads and writes"| node_database
node_template_service -->|"reads and writes"| node_database
node_profile -->|"requires identity"| node_auth_guard
node_planner_logic -.->|"may consult"| node_capacity

click node_app "https://github.com/danven-ong/nusgyms/blob/main/frontend/src/App.tsx"
click node_auth_pages "https://github.com/danven-ong/nusgyms/tree/main/frontend/src/pages"
click node_workout_pages "https://github.com/danven-ong/nusgyms/tree/main/frontend/src/pages"
click node_planner_pages "https://github.com/danven-ong/nusgyms/blob/main/frontend/src/pages/PlannerPage.tsx"
click node_backend "https://github.com/danven-ong/nusgyms/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/danven-ong/nusgyms/blob/main/backend/src/routes/authRoutes.ts"
click node_auth_controller "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/authController.ts"
click node_auth_service "https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/auth.ts"
click node_auth_guard "https://github.com/danven-ong/nusgyms/blob/main/backend/src/middleware/authMiddleware.ts"
click node_settings "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/settingsController.ts"
click node_template_controller "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutTemplateController.ts"
click node_session_controller "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutSessionController.ts"
click node_workout_service "https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workout.ts"
click node_session_service "https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workoutSession.ts"
click node_template_service "https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workoutTemplate.ts"
click node_planner_routes "https://github.com/danven-ong/nusgyms/blob/main/backend/src/routes/plannerRoutes.ts"
click node_planner_controller "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/plannerController.ts"
click node_planner_logic "https://github.com/danven-ong/nusgyms/tree/main/backend/src/services"
click node_capacity "https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/gymCapacity.ts"
click node_analytics "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/analyticsController.ts"
click node_profile "https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/profileController.ts"
click node_database "https://github.com/danven-ong/nusgyms/blob/main/backend/src/db/index.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_app,node_auth_pages,node_workout_pages,node_planner_pages,node_user toneBlue
class node_auth_routes,node_auth_controller,node_auth_service,node_auth_guard,node_settings,node_database toneAmber
class node_template_controller,node_session_controller,node_workout_service,node_session_service,node_template_service,node_backend toneMint
class node_planner_routes,node_planner_controller,node_planner_logic,node_capacity toneRose
class node_analytics,node_profile toneIndigo
```

## Components

### Web application

- [Frontend routes](https://github.com/danven-ong/nusgyms/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Account pages](https://github.com/danven-ong/nusgyms/tree/main/frontend/src/pages): `frontend/src/pages`
- [Workout pages](https://github.com/danven-ong/nusgyms/tree/main/frontend/src/pages): `frontend/src/pages`
- [Planner pages](https://github.com/danven-ong/nusgyms/blob/main/frontend/src/pages/PlannerPage.tsx): `frontend/src/pages/PlannerPage.tsx`

### Accounts and settings

- [Auth routes](https://github.com/danven-ong/nusgyms/blob/main/backend/src/routes/authRoutes.ts): `backend/src/routes/authRoutes.ts`
- [Account handlers](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/authController.ts): `backend/src/controllers/authController.ts`
- [Identity service](https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/auth.ts): `backend/src/services/auth.ts`
- [Token guard](https://github.com/danven-ong/nusgyms/blob/main/backend/src/middleware/authMiddleware.ts): `backend/src/middleware/authMiddleware.ts`
- [Account settings](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/settingsController.ts): `backend/src/controllers/settingsController.ts`

### Workout tracking

- [Template handlers](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutTemplateController.ts): `backend/src/controllers/workoutTemplateController.ts`
- [Session handlers](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/workoutSessionController.ts): `backend/src/controllers/workoutSessionController.ts`
- [Workout service](https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workout.ts): `backend/src/services/workout.ts`
- [Session service](https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workoutSession.ts): `backend/src/services/workoutSession.ts`
- [Template service](https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/workoutTemplate.ts): `backend/src/services/workoutTemplate.ts`

### Planning and capacity

- [Planner routes](https://github.com/danven-ong/nusgyms/blob/main/backend/src/routes/plannerRoutes.ts): `backend/src/routes/plannerRoutes.ts`
- [Planner handlers](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/plannerController.ts): `backend/src/controllers/plannerController.ts`
- [Planner services](https://github.com/danven-ong/nusgyms/tree/main/backend/src/services): `backend/src/services`
- [Gym capacity](https://github.com/danven-ong/nusgyms/blob/main/backend/src/services/gymCapacity.ts): `backend/src/services/gymCapacity.ts`

### Progress and profile

- [Workout analytics](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/analyticsController.ts): `backend/src/controllers/analyticsController.ts`
- [Profile and weight](https://github.com/danven-ong/nusgyms/blob/main/backend/src/controllers/profileController.ts): `backend/src/controllers/profileController.ts`

### Other components

- **Gym user**
- [API application](https://github.com/danven-ong/nusgyms/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [PostgreSQL](https://github.com/danven-ong/nusgyms/blob/main/backend/src/db/index.ts): `backend/src/db/index.ts`

## Connections

- Gym user → Frontend routes: uses (evidence: `frontend/src/App.tsx`)
- Frontend routes → Account pages: routes to (evidence: `frontend/src/App.tsx`)
- Frontend routes → Workout pages: routes to (evidence: `frontend/src/App.tsx`)
- Frontend routes → Planner pages: routes to (evidence: `frontend/src/App.tsx`)
- Frontend routes → API application: requests
- API application → Auth routes: mounts (evidence: `backend/src/app.ts`)
- API application → Planner routes: mounts (evidence: `backend/src/app.ts`)
- Auth routes → Account handlers: dispatches (evidence: `backend/src/routes/authRoutes.ts`)
- Auth routes → Token guard: authenticates (evidence: `backend/src/routes/authRoutes.ts`)
- Account handlers → Identity service: calls (evidence: `backend/src/controllers/authController.ts`)
- Account handlers → Token guard: uses identity (evidence: `backend/src/controllers/authController.ts`)
- Account settings → Identity service: sends OTP (evidence: `backend/src/controllers/settingsController.ts`)
- Planner routes → Planner handlers: dispatches (evidence: `backend/src/routes/plannerRoutes.ts`)
- Planner routes → Token guard: authenticates (evidence: `backend/src/routes/plannerRoutes.ts`)
- Planner handlers → Planner services: delegates (evidence: `backend/src/controllers/plannerController.ts`)
- Template handlers → Template service: calls (evidence: `backend/src/controllers/workoutTemplateController.ts`)
- Template handlers → Session service: calls (evidence: `backend/src/controllers/workoutTemplateController.ts`)
- Template handlers → Workout service: calls (evidence: `backend/src/controllers/workoutTemplateController.ts`)
- Session handlers → Template service: loads template (evidence: `backend/src/controllers/workoutSessionController.ts`)
- Session handlers → Session service: creates session (evidence: `backend/src/controllers/workoutSessionController.ts`)
- Session handlers → Workout service: stores sets (evidence: `backend/src/controllers/workoutSessionController.ts`)
- Workout service → PostgreSQL: reads and writes (evidence: `backend/src/services/workout.ts`)
- Session service → PostgreSQL: reads and writes (evidence: `backend/src/services/workoutSession.ts`)
- Template service → PostgreSQL: reads and writes (evidence: `backend/src/services/workoutTemplate.ts`)
- Profile and weight → Token guard: requires identity (evidence: `backend/src/controllers/profileController.ts`)
- Planner services → Gym capacity: may consult
