# z-ghazanfar/fitos architecture

> Architecture diagram of the GitHub repository z-ghazanfar/fitos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z-ghazanfar/fitos
- Repository: https://github.com/z-ghazanfar/fitos

## Overview

1. **Overall shape**
   FitOS is a Next.js App Router application that acts as a private fitness “OS” on top of Postgres/Prisma. The app has both interactive pages and a set of API routes that ingest, sync, and expose fitness data to external systems.

2. **Primary UI surfaces**
   The user-facing app is centered on `/`, `/training`, `/nutrition`, `/recovery`, and `/settings`, with auth pages for `/login` and `/signup`. The UI is mainly a dashboard over stored data, not a data-entry-heavy app; most write flows happen through API endpoints, integrations, or GPT actions.

3. **Core data store and boundaries**
   Prisma is the persistence boundary for users, fitness records, integration state, OAuth clients/tokens, and coach profile history. The schema is explicitly designed for multi-user operation with `user_id` on core tables, while the app currently behaves like a private invite-only system.

4. **Authentication and user identity**
   The app uses its own signed HTTP-only session cookie rather than relying on a third-party session provider. It supports email/password login plus Google sign-in, and Google accounts are linked to existing invited users by matching email. Public signup is optional and controlled by configuration.

5. **Encrypted secrets and integration credentials**
   Sensitive integration material is stored encrypted at rest with AES-256-GCM. This matters architecturally because WHOOP OAuth tokens, Hevy API keys, and similar credentials are not treated as plain application data; the app has a dedicated security layer for them.

6. **WHOOP integration pipeline**
   WHOOP is connected through OAuth, then used in two ways: scheduled daily syncs and webhook-driven event capture. Webhooks are stored and de-duplicated, but the scheduled reconciliation job is the authoritative backstop that re-fetches recent WHOOP windows and updates daily recovery/body measurement context.

7. **Hevy integration pipeline**
   Hevy is integrated as a read-heavy source for workout history and progression analysis. The app supports full workout backfill plus incremental event sync, stores workouts at set-level granularity, and then uses that stored history for training dashboards and recommendation generation. The recommendation engine is intentionally read-only and does not write back to Hevy.

8. **Nutrition ingestion and daily totals**
   Nutrition is centered on a daily aggregate record rather than individual meals. The key write path is the GPT Action endpoint `PUT /api/actions/nutrition/day`, which overwrites a user’s daily calories and macros for a date. Historical nutrition can also be imported from CSV, and the `/nutrition` page is for review/trends rather than detailed meal tracking.

9. **Weight logging**
   Weight history comes from a dedicated ingestion endpoint for Apple Health / Shortcuts, `POST /api/actions/weight/log`. This exists because Apple Health is not directly web-accessible, so the system expects weight samples to arrive from an iPhone Shortcut or CSV import and then uses them for trend views and AI context.

10. **Shared GPT OAuth and AI coach endpoints**
    The app exposes an OAuth-secured GPT action surface so a shared Custom GPT can act on behalf of the signed-in user. Separate AI endpoints provide structured context for snapshots, progression, recovery/training, workouts, and a coach report. The GPT can also update the persistent coach profile, which stores goal, phase, priorities, notes, and revision history.

11. **Sync architecture**
    Sync is split between user-triggered and scheduled paths. There are per-source sync routes, a combined `/api/sync/all`, and cron-oriented endpoints for WHOOP daily sync, WHOOP reconcile, Hevy events, and recommendation generation. The sync layer pulls from external APIs, normalizes data into the database, and then powers both dashboards and AI context.

12. **External services and trust boundaries**
    The architecture crosses several external boundaries: Google for login, WHOOP for recovery/body metrics and webhooks, Hevy for workout data, ChatGPT for GPT Actions/OAuth, and Apple Health via Shortcuts for weight. The app’s main trust boundaries are its session cookie, its OAuth-protected GPT action API, and its internal-secret-protected scheduler/webhook routes.

13. **Key product flow**
    The main end-to-end flow is: external fitness data is synchronized into Postgres, dashboards read it back for trends and status, and the shared GPT consumes the same stored data through OAuth APIs to generate coaching context or update nutrition/coach profile state. This makes the database the central source of truth for both UI and AI-assisted workflows.

Main entry points: [`app/components/app-frame.tsx`](https://github.com/z-ghazanfar/fitos/blob/main/app/components/app-frame.tsx) (Shared UI), [`prisma/schema.prisma`](https://github.com/z-ghazanfar/fitos/blob/main/prisma/schema.prisma) (Prisma DB), [`lib/auth/session.ts`](https://github.com/z-ghazanfar/fitos/blob/main/lib/auth/session.ts) (Auth core), [`app/api/oauth/token/route.ts`](https://github.com/z-ghazanfar/fitos/blob/main/app/api/oauth/token/route.ts) (GPT actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI surfaces"]
  node_app_shell["App shell<br/>Next.js shell<br/>[layout.tsx]"]
  node_home_dashboard["Home<br/>dashboard page<br/>[page.tsx]"]
  node_training_page["Training<br/>dashboard page<br/>[page.tsx]"]
  node_nutrition_page["Nutrition<br/>dashboard page<br/>[page.tsx]"]
  node_recovery_page["Recovery<br/>dashboard page<br/>[page.tsx]"]
  node_settings_page["Settings<br/>[page.tsx]"]
  node_auth_pages["Auth pages<br/>login/signup pages<br/>[page.tsx]"]
  node_app_components["Shared UI<br/>components<br/>[app-frame.tsx]"]
end

subgraph group_api["API boundary"]
  node_auth_routes["Auth API<br/>auth routes<br/>[route.ts]"]
  node_gpt_actions["GPT actions<br/>OAuth APIs<br/>[route.ts]"]
  node_ai_endpoints["AI endpoints<br/>AI APIs<br/>[route.ts]"]
  node_sync_routes["Sync routes<br/>sync APIs<br/>[route.ts]"]
  node_whoop_api["WHOOP API<br/>integration routes<br/>[route.ts]"]
  node_hevy_sync["Hevy sync<br/>integration sync<br/>[route.ts]"]
end

subgraph group_core["Core logic"]
  node_security_layer["Crypto<br/>security module<br/>[crypto.ts]"]
  node_auth_core["Auth core<br/>session + identity<br/>[session.ts]"]
  node_coach_ai["Coach AI<br/>context + profile<br/>[coach-profile.ts]"]
  node_sync_engine["Sync engine<br/>domain sync<br/>[sync.ts]"]
  node_integration_clients["Integration clients<br/>source adapters<br/>[whoop.ts]"]
  node_nutrition_weight["Nutrition/weight<br/>domain modules<br/>[nutrition.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_db[("Prisma DB<br/>schema<br/>[schema.prisma]")]
  node_external_services(("External services<br/>trust boundaries"))
end

node_app_shell -->|"uses"| node_app_components
node_home_dashboard -->|"renders"| node_app_components
node_training_page -->|"renders"| node_app_components
node_nutrition_page -->|"renders"| node_app_components
node_recovery_page -->|"renders"| node_app_components
node_settings_page -->|"renders"| node_app_components
node_auth_pages -->|"uses"| node_auth_core
node_auth_routes -->|"uses"| node_auth_core
node_auth_routes -->|"reads/writes"| node_prisma_db
node_auth_routes -.->|"Google sign-in"| node_external_services
node_gpt_actions -->|"authenticates"| node_auth_core
node_gpt_actions -->|"writes"| node_nutrition_weight
node_gpt_actions -->|"updates"| node_coach_ai
node_ai_endpoints -->|"reads"| node_coach_ai
node_ai_endpoints -->|"reads"| node_sync_engine
node_sync_routes -->|"orchestrates"| node_sync_engine
node_sync_routes -->|"pulls"| node_integration_clients
node_whoop_api -->|"webhooks/OAuth"| node_integration_clients
node_hevy_sync -->|"pulls"| node_integration_clients
node_integration_clients -.->|"connects"| node_external_services
node_security_layer -->|"protects"| node_prisma_db
node_sync_engine -->|"persists"| node_prisma_db
node_coach_ai -->|"reads/writes"| node_prisma_db
node_nutrition_weight -->|"reads/writes"| node_prisma_db
node_auth_core -->|"reads/writes"| node_prisma_db
node_auth_core -->|"protects"| node_security_layer
node_coach_ai -.->|"ChatGPT"| node_external_services
node_gpt_actions -.->|"GPT OAuth"| node_external_services

click node_app_shell "https://github.com/z-ghazanfar/fitos/blob/main/app/layout.tsx"
click node_home_dashboard "https://github.com/z-ghazanfar/fitos/blob/main/app/page.tsx"
click node_training_page "https://github.com/z-ghazanfar/fitos/blob/main/app/training/page.tsx"
click node_nutrition_page "https://github.com/z-ghazanfar/fitos/blob/main/app/nutrition/page.tsx"
click node_recovery_page "https://github.com/z-ghazanfar/fitos/blob/main/app/recovery/page.tsx"
click node_settings_page "https://github.com/z-ghazanfar/fitos/blob/main/app/settings/page.tsx"
click node_auth_pages "https://github.com/z-ghazanfar/fitos/blob/main/app/login/page.tsx"
click node_app_components "https://github.com/z-ghazanfar/fitos/blob/main/app/components/app-frame.tsx"
click node_auth_routes "https://github.com/z-ghazanfar/fitos/blob/main/app/api/auth/google/callback/route.ts"
click node_gpt_actions "https://github.com/z-ghazanfar/fitos/blob/main/app/api/oauth/token/route.ts"
click node_ai_endpoints "https://github.com/z-ghazanfar/fitos/blob/main/app/api/ai/snapshot/route.ts"
click node_sync_routes "https://github.com/z-ghazanfar/fitos/blob/main/app/api/sync/all/route.ts"
click node_whoop_api "https://github.com/z-ghazanfar/fitos/blob/main/app/api/whoop/connect/route.ts"
click node_hevy_sync "https://github.com/z-ghazanfar/fitos/blob/main/app/api/sync/hevy/backfill/route.ts"
click node_security_layer "https://github.com/z-ghazanfar/fitos/blob/main/lib/security/crypto.ts"
click node_auth_core "https://github.com/z-ghazanfar/fitos/blob/main/lib/auth/session.ts"
click node_coach_ai "https://github.com/z-ghazanfar/fitos/blob/main/lib/ai/coach-profile.ts"
click node_sync_engine "https://github.com/z-ghazanfar/fitos/blob/main/lib/sync.ts"
click node_integration_clients "https://github.com/z-ghazanfar/fitos/blob/main/lib/integrations/whoop.ts"
click node_nutrition_weight "https://github.com/z-ghazanfar/fitos/blob/main/lib/nutrition.ts"
click node_prisma_db "https://github.com/z-ghazanfar/fitos/blob/main/prisma/schema.prisma"

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_shell,node_home_dashboard,node_training_page,node_nutrition_page,node_recovery_page,node_settings_page,node_auth_pages,node_app_components toneBlue
class node_auth_routes,node_gpt_actions,node_ai_endpoints,node_sync_routes,node_whoop_api,node_hevy_sync toneAmber
class node_security_layer,node_auth_core,node_coach_ai,node_sync_engine,node_integration_clients,node_nutrition_weight toneMint
class node_prisma_db,node_external_services toneRose
```

## Components

### UI surfaces

App Router pages and shared dashboard components

- [App shell](https://github.com/z-ghazanfar/fitos/blob/main/app/layout.tsx): Next.js shell · Root layout, global styles, and shared frame for the dashboard · `app/layout.tsx`
- [Home](https://github.com/z-ghazanfar/fitos/blob/main/app/page.tsx): dashboard page · Main overview surface for the private fitness OS · `app/page.tsx`
- [Training](https://github.com/z-ghazanfar/fitos/blob/main/app/training/page.tsx): dashboard page · Training trends and workout-focused UI · `app/training/page.tsx`
- [Nutrition](https://github.com/z-ghazanfar/fitos/blob/main/app/nutrition/page.tsx): dashboard page · Daily nutrition review and trends · `app/nutrition/page.tsx`
- [Recovery](https://github.com/z-ghazanfar/fitos/blob/main/app/recovery/page.tsx): dashboard page · Recovery and body metric views · `app/recovery/page.tsx`
- [Settings](https://github.com/z-ghazanfar/fitos/blob/main/app/settings/page.tsx): settings page · Account and integration controls · `app/settings/page.tsx`
- [Auth pages](https://github.com/z-ghazanfar/fitos/blob/main/app/login/page.tsx): login/signup pages · Sign-in and account creation entry points · `app/login/page.tsx`
- [Shared UI](https://github.com/z-ghazanfar/fitos/blob/main/app/components/app-frame.tsx): components · Dashboard frame, charts, and command-center widgets · `app/components/app-frame.tsx`

### API boundary

Authentication, GPT actions, sync, and integration routes

- [Auth API](https://github.com/z-ghazanfar/fitos/blob/main/app/api/auth/google/callback/route.ts): auth routes · Password auth, Google callback, and session handling endpoints · `app/api/auth/google/callback/route.ts`
- [GPT actions](https://github.com/z-ghazanfar/fitos/blob/main/app/api/oauth/token/route.ts): OAuth APIs · OAuth-protected action surface for nutrition, weight, and shared GPT access · `app/api/oauth/token/route.ts`
- [AI endpoints](https://github.com/z-ghazanfar/fitos/blob/main/app/api/ai/snapshot/route.ts): AI APIs · Structured coach, snapshot, progression, and workout context APIs · `app/api/ai/snapshot/route.ts`
- [Sync routes](https://github.com/z-ghazanfar/fitos/blob/main/app/api/sync/all/route.ts): sync APIs · Combined and source-specific sync endpoints plus cron backstops · `app/api/sync/all/route.ts`
- [WHOOP API](https://github.com/z-ghazanfar/fitos/blob/main/app/api/whoop/connect/route.ts): integration routes · OAuth connect/callback, webhook intake, and reconciliation support · `app/api/whoop/connect/route.ts`
- [Hevy sync](https://github.com/z-ghazanfar/fitos/blob/main/app/api/sync/hevy/backfill/route.ts): integration sync · Workout backfill and incremental event ingestion from Hevy · `app/api/sync/hevy/backfill/route.ts`

### Core logic

Auth, AI, sync, security, and domain helpers

- [Crypto](https://github.com/z-ghazanfar/fitos/blob/main/lib/security/crypto.ts): security module · AES-GCM encryption for stored integration secrets and tokens · `lib/security/crypto.ts`
- [Auth core](https://github.com/z-ghazanfar/fitos/blob/main/lib/auth/session.ts): session + identity · Signed cookie sessions, password auth, Google linking, and redirect logic · `lib/auth/session.ts`
- [Coach AI](https://github.com/z-ghazanfar/fitos/blob/main/lib/ai/coach-profile.ts): context + profile · Coach profile state, structured context, and report generation logic · `lib/ai/coach-profile.ts`
- [Sync engine](https://github.com/z-ghazanfar/fitos/blob/main/lib/sync.ts): domain sync · Normalization and orchestration across fitness sources and recommendations · `lib/sync.ts`
- [Integration clients](https://github.com/z-ghazanfar/fitos/blob/main/lib/integrations/whoop.ts): source adapters · Hevy and WHOOP client wrappers and webhook handling helpers · `lib/integrations/whoop.ts`
- [Nutrition/weight](https://github.com/z-ghazanfar/fitos/blob/main/lib/nutrition.ts): domain modules · Daily nutrition totals and weight trend helpers · `lib/nutrition.ts`

### Persistence

Prisma schema and database boundary

- [Prisma DB](https://github.com/z-ghazanfar/fitos/blob/main/prisma/schema.prisma): schema · Primary persistence boundary for users, fitness records, integrations, and coach history · `prisma/schema.prisma`
- **External services**: trust boundaries · Google, WHOOP, Hevy, ChatGPT, and Apple Health/Shortcuts

## Connections

- App shell → Shared UI: uses · Shared shell composes reusable dashboard widgets
- Home → Shared UI: renders · Home page uses the shared frame and charts
- Training → Shared UI: renders · Training UI is built from shared dashboard components
- Nutrition → Shared UI: renders · Nutrition UI uses shared primitives and charts
- Recovery → Shared UI: renders · Recovery UI reuses the common app frame
- Settings → Shared UI: renders · Settings surface is part of the same shell
- Auth pages → Auth core: uses · Login and signup pages delegate authentication behavior
- Auth API → Auth core: uses · Auth endpoints mint and validate signed sessions
- Auth API → Prisma DB: reads/writes · Accounts and session-linked user records are persisted
- Auth API → External services: Google sign-in · OAuth callback links Google accounts to invited users
- GPT actions → Auth core: authenticates · Shared GPT action surface is tied to the signed-in user
- GPT actions → Nutrition/weight: writes · Nutrition and weight actions update daily history
- GPT actions → Coach AI: updates · GPT can revise persistent coach profile state
- AI endpoints → Coach AI: reads · Coach report and context endpoints assemble AI-ready views
- AI endpoints → Sync engine: reads · AI endpoints consume normalized fitness data
- Sync routes → Sync engine: orchestrates · User-triggered and scheduled sync entry points drive the engine
- Sync routes → Integration clients: pulls · Sync routes fetch and normalize external fitness data
- WHOOP API → Integration clients: webhooks/OAuth · WHOOP connect and webhook routes bridge the external service
- Hevy sync → Integration clients: pulls · Hevy backfill and events routes ingest workout history
- Integration clients → External services: connects · WHOOP and Hevy are source systems outside the app boundary
- Crypto → Prisma DB: protects · Encrypted-at-rest secret handling guards stored credentials
- Sync engine → Prisma DB: persists · Normalized workouts, recovery, nutrition, and integration state land in Postgres
- Coach AI → Prisma DB: reads/writes · Coach profile history and AI context are stored centrally
- Nutrition/weight → Prisma DB: reads/writes · Daily nutrition totals and weight samples are stored for trends
- Auth core → Prisma DB: reads/writes · Users, invitation state, and linked identities are persisted
- Auth core → Crypto: protects · Session and credential handling rely on encrypted secrets
- Coach AI → External services: ChatGPT · Shared GPT and AI endpoints are served through OpenAI/ChatGPT
- GPT actions → External services: GPT OAuth · Custom GPT accesses the app through an OAuth-secured boundary