Architecture overview

A bird’s-eye view of how FitKit is structured. Each section below either has a dedicated deep-dive (api.md, web.md, database.md, etc.) or links into the code.

Monorepo layout

Nx workspace, pnpm package manager. Two distinct kinds of project: applications (apps/) and libraries (libs/).

fitkit/
├── apps/
│   ├── api/         NestJS backend (port 3001)
│   ├── web/         Next.js 16 customer + dashboard app (port 3000)
│   ├── admin/       Vite + React internal-only admin console
│   ├── marketing/   Astro marketing site (separate Railway deploy)
│   ├── minisites/   Astro per-org public minisite renderer
│   └── docs/        Nextra-rendered docs site (this tree, served on port 3030)
├── libs/
│   ├── db/          @fitkit/db — Drizzle schema + client
│   └── shared/      @fitkit/shared — Zod schemas + TS types shared API↔web↔mobile
├── docs/            this tree (canonical markdown source for apps/docs)
└── scripts/         dev/test scripts, enrichment one-offs

The native member app (fitkit-mobile) lives in a separate repo sibling on disk (~/dev/fitkit-mobile/), not under apps/. It consumes @fitkit/shared as a versioned GitHub Packages dependency. See mobile.md for the rationale (toolchain divergence, EAS pipeline, native artifact churn).

Apps at a glance

Libs at a glance

Path aliases come from tsconfig.base.json.

Request flow (clients → API)

The API is the single source of business truth. Three first-class clients today; more planned.

Browser                    fitkit-mobile (iOS/Android)
   │                           │
   ▼  HTTPS                    ▼  HTTPS
Next.js (Vercel)           Expo Router app
   │  • Middleware             │  • Clerk Expo session
   │    (apps/web/src/         │    (token cache in
   │     middleware.ts):       │     expo-secure-store)
   │    - locale detection     │  • useApi() hook attaches
   │    - Clerk auth on        │    Clerk bearer + X-Locale
   │      protected routes     │  • 10s JWT cache + single
   │    - legacy dashboard     │    401 retry
   │      path redirects       │
   │  Server components:       │
   │    - serverFetch(path)    │
   │      attaches bearer      │
   │  Client components:       │
   │    - useApi() hook        │
   │      attaches bearer      │
   ▼                           ▼
        NestJS API (Railway)
   │
   │  Global pipeline:
   │     1. Helmet, CORS, compression
   │     2. ValidationPipe (whitelist + transform)
   │     3. AuthGuard (verifies Clerk JWT, loads DB user)
   │     4. PlatformTierGuard (org-tier feature gates)
   │     5. ThrottlerGuard (60 req / 60s default)
   │     6. LoggingInterceptor (Pino + Sentry scope)
   │     7. CacheControlInterceptor
   │     8. AllExceptionsFilter (Sentry + structured error body)
   ▼
   │
   │  Global pipeline:
   │     1. Helmet, CORS, compression
   │     2. ValidationPipe (whitelist + transform)
   │     3. AuthGuard (verifies Clerk JWT, loads DB user)
   │     4. PlatformTierGuard (org-tier feature gates)
   │     5. ThrottlerGuard (60 req / 60s default)
   │     6. LoggingInterceptor (Pino + Sentry scope)
   │     7. CacheControlInterceptor
   │     8. AllExceptionsFilter (Sentry + structured error body)
   ▼
PostgreSQL (Drizzle ORM)

Public endpoints opt out of auth with @Public(). Health check (/health) and Clerk webhook (/webhooks/clerk) are the canonical examples. See architecture/api.md for the full pipeline.

Real-time / WebSocket flow

Browser, fitkit-mobile ⇄ Socket.IO ⇄ apps/api (NestJS WS gateways)
                                      │
                                      ▼
                                  Redis (pub/sub)
                                      │
                                      ▼
                              Other apps/api instances

apps/api/src/main.ts wires the Socket.IO Redis adapter when REDIS_URL is set. Without Redis the server falls back to the in-process adapter — single-instance only. Used for messaging, typing indicators, presence, and live update fan-out.

Mobile uses socket.io-client with transports: ['websocket'] only and AppState-driven reconnect (foreground → connect, background → disconnect). See mobile.md for the lifecycle details.

Background jobs (BullMQ)

Producers (services in apps/api/src/**) ─→ BullMQ queues ─→ Redis ─→ Workers (in-process)

Queues registered today (greppable via BullModule.registerQueue):

Bull-Board UI (apps/api/src/bull-board/) exposes queue state internally.

In-process event bus

NestJS EventEmitterModule.forRoot() is enabled globally in app.module.ts. Subsystems emit domain events (e.g. membership.activated) and other modules subscribe via @OnEvent. Canonical example: the Forms module’s onboarding hook (apps/api/src/forms/forms.service.ts Onboarding auto-issue block) listens for membership activation and auto-issues configured compliance forms.

This is intentionally separate from BullMQ — events are in-process, synchronous within the worker, no persistence. Use BullMQ when you need retries, scheduling, or cross-process delivery.

File storage

Cloudflare R2. Two logical buckets:

Module: apps/api/src/r2/. All reads presign a fresh URL (1h default) — no public URLs are served.

Observability

See architecture/observability.md for the deep dive (sample rates, beforeSend filters, audit-log gap).

Deployment

PostgreSQL and Redis in production are managed (Neon for DB is the documented default; Railway managed Redis). Local dev uses docker-compose.yml — Postgres on 5432 (pgvector image), Redis on 6379. Test stack uses docker-compose.test.yml — Postgres on 55432, Redis on 56379.

Where to read next

• api.md — NestJS modules, global pipeline, DI tokens.
• web.md — Next.js routing, providers, data helpers, feature gating.
• database.md — schema domains, migration policy, encryption.
• auth.md — Clerk on both sides, multi-org, webhooks.
• i18n.md — locale model, RTL, dictionary discipline.
• observability.md — Sentry/PostHog/Pino + audit-log gap.
• infra.md — hosting, env vars, CI workflows, secrets.