FitKit Documentation

The single source of truth for what FitKit is, how it’s built, how it ships, and how it’s tested.

Everything in _archive/ is older planning material kept for context only — do not treat it as current.

Start here if you’re…

New engineer joining the team → overview/product-vision.md, then architecture/overview.md, then the feature folder you’ll be touching under features/.
New agent picking up a task → overview/glossary.md for domain vocabulary, architecture/overview.md for the system map, then the relevant feature doc in features/<area>/.
QA contractor → testing/qa-contractor-onboarding.md. Read overview/personas.md next; pick up per-feature qa-plan.md files from features/.
PM / stakeholder → overview/product-vision.md, overview/personas.md, overview/roadmap.md.
On-call / debugging prod → runbooks/, then architecture/observability.md.

Sections

`overview/`

The “what” and “why” of the product.

File	What it covers
`product-vision.md`	Mission, market, differentiation, multi-client vision
`personas.md`	Member, Coach, Studio Owner, Platform Admin — day-in-the-life and JTBD
`glossary.md`	Domain term reference (Plan vs Subscription, Form Template vs Instance, etc.)
`roadmap.md`	Shipped, in-progress, near-term, longer-term — keyed to Linear issue IDs

`architecture/`

The “how” of the system. Read these in order if you’re new.

File	What it covers
`overview.md`	Monorepo layout, request flow, infra at a glance
`api.md`	NestJS modules, guards, interceptors, DI tokens, response convention
`web.md`	Next.js 16 app router, middleware, i18n, data fetching helpers
`mobile.md`	`fitkit-mobile` Expo / React Native app — routes, providers, push, deep links, EAS
`database.md`	Drizzle schema domains, migration policy, encryption at rest, pgvector
`auth.md`	Clerk integration on web + API, user sync, multi-org, invitations
`i18n.md`	en/he/ru, RTL for Hebrew, dictionary discipline
`observability.md`	Sentry, PostHog, Pino, Bull-Board, audit logging gap
`infra.md`	Hosting, environments, CI workflows, secrets, encryption keys

`features/`

One folder per product area (features/scheduling-bookings/, features/forms/, etc.). Each carries an overview, API contracts, and a qa-plan.md. This README does not list every feature — browse the folder. Another agent owns these docs; do not edit them from this folder.

`runbooks/`

Operational procedures: local environment setup, common incidents, manual data fixes. Currently sparse — env-setup.md is the canonical local-dev recipe.

`testing/`

File	What it covers
`strategy.md`	Test pyramid (unit / int / e2e), commands, CI gates
`driver-pattern.md`	The driver contract used by unit, integration, and E2E tests
`qa-contractor-onboarding.md`	Onboarding for external QA contractors

`decisions/`

Architecture Decision Records. Add a new one when locking in a non-obvious choice (e.g. why JSONB for notification prefs, why no audit log yet, why middleware-WhatsApp before direct Meta).

`_archive/`

Older PRDs, planning docs, partnership notes, marketing drafts. Reference only. Anything in _archive/ predates the current product reality — reconcile against code before quoting.

Conventions

File paths and identifiers in backticks: apps/api/src/forms/forms.service.ts.
Linear issues as FIT-XXX.
Today’s reference date for “current”/“recent” language: 2026-05-28.
Cross-link aggressively. If a claim depends on another doc, link to it.
Tables for module lists, route maps, state machines.
Present tense. Third person. No marketing fluff in docs.

Source of truth ordering

When docs disagree:

The code wins.
This docs/ tree wins over _archive/.
CLAUDE.md wins over docs for agent-specific behavioural rules.