z-ghazanfar/fitos

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.