Legacy docs corrections

The repo carries hand written notes under backend/docs/. They were accurate when the backend was a domain only API with three auth lanes. The code has moved on. This page lists what is stale in each file so you do not act on it. When a note and the code disagree, the code is right.

The big change behind most of it

The older notes describe this split: the web app owns identity and billing, the backend owns domain data, and the backend calls the web app to verify sessions. What the code does now:

better-auth runs inside the API process (@repo/auth), served under /api/auth.
Billing runs inside the API process (@repo/payments, the Polar webhook at /api/webhooks/payments, the oRPC payments procedures).
The oRPC procedures, mail, avatar storage, coach notifications and the auth database client all live in this repo as @repo/* packages.
One Postgres database holds both the auth schema and the public schema.

So the statement in docs/README.md that the service is “everything that is not authentication or billing” is no longer true.

`README.md` (docs index)

Says	Now
TypeScript 5.8, Prisma 6, pnpm 10	TypeScript `6.0.3`, Prisma `7.8.0`, Zod `4.4.2`, `pnpm@11.5.0` in `packageManager`.
Layout lists `apps/core-api` and the `@perform/*` packages	There is also `apps/mcp-server` and ten `@repo/*` packages. See Packages overview.
Coach authentication and billing live in the web repo	They run in this process. See Authentication and Billing and plan limits.

`ARCHITECTURE.md`

Says	Now
Three lanes: bearer, web gateway, trainee	Eleven surfaces. Added since: `/api`, `/mcp`, partner, automation API, public, public signing, `/v1/admin`, the agent webhook. See Route lanes.
The bearer lane is for the trainee mobile app	The trainee app uses `/v1/trainee` with its own token. The bearer lane mounts three routers and takes its studio id from the session’s organization id.
`web = [serviceAuth, webUserContext()]`	`web = [serviceAuth, webUserContext(ctx.prisma), webLimiter]`. The context middleware takes Prisma because it resolves and provisions the studio and the owner’s coach row.
The web app forwards three headers	It also forwards `x-studio-name`, `x-studio-slug`, `x-user-name` and `x-user-email`.
`x-studio-id` becomes `req.auth.studioId`	The header carries the organization id. `webUserContext` maps it to `Studio.id` through `externalOrgId`.
`request-otp` matches a client on the last 9 digits	It reduces the number to its national core, loads candidates by variants and keeps exact core matches only.
OTP is sent with the studio’s key or the global `SMARTSEND_API_KEY`	Order is `SMARTSEND_OTP_API_KEY`, then `SMARTSEND_API_KEY`, then the studio’s key.
`verify-otp` returns `{ token, client, studio }`	It also returns `studios`, every studio the number trains at.
`GET /v1/trainee/me` is the protected route of the lane	The lane has dozens of protected routes and eight more routers under `/v1/trainee/*`. See Trainee sessions.
The request flow diagram	Misses `/api`, `/mcp`, the scoped body parsers, partner, automation and public lanes. See Backend overview.
Modules table with 18 modules	`modules/` has 49 folders. `modules/index.ts` is the list of what is mounted.
`AppContext` is env, prisma, queue, smartsend, logger	It also has `nonceStore`, `serviceSecrets` and `auth`.
`@perform/db` is the Prisma client factory and the schema	`@perform/db` re-exports the client from `@repo/database` and owns migrations and seed. See Database packages.
Workers run in a separate process	Workers start in `server.ts` in the API process.
`PerformQueue` names WhatsApp sends, churn scans, PDF export, AI meal parsing, data export	Those five names are declared and unused. Eleven other queues are live. See Queues and jobs.
The dashboard is WebSocket driven with Redis fan-out	There is no WebSocket code or dependency in the repo.

`API_CONVENTIONS.md`

Says	Now
Two prefixes for the same modules, `/v1/<module>` and `/v1/web/<module>`	Only `studios`, `clients` and `whatsapp` are on both. Everything else for coaches is on `/v1/web` only.
Error code table with eight codes	There is a ninth, `SERVICE_UNAVAILABLE` (503).
`FORBIDDEN` is for an insufficient role	It is also used for plan limits, a locked app and preview tokens, with `details.reason`.
`pageSize` default 20, max 100	The maximum is set per schema and varies. `productListQuery` allows 500.
One response envelope	The automation API, the signing lane, the waitlist route, `/mcp` and `/api` each answer differently. See Responses and errors.
Bearer and web lanes send replay headers on every call	True for those two. The trainee app, API key callers and webhooks send none.

The section on trainee health samples and the HEART_RATE compatibility rules still matches the code.

`ADDING_A_FEATURE.md`

Says	Now
Edit `packages/db/prisma/schema.prisma` and migrate	Edit both schemas and rebuild `@repo/database`. See Adding a module.
`web` is `[serviceAuth, webUserContext()]`	Three elements, see above.
Mount on the bearer lane if the mobile app needs it	The mobile app is the trainee app. Add a trainee router guarded by `authenticateTrainee`.
Tests under `tests/unit` and `tests/integration`	One flat `tests/` folder. See Testing.

`CODING_STANDARDS.md`

Says	Now
Code carries no comments. None.	The code has many explanatory comments, mostly recording why a decision was made (see `app.ts`, the workers, `billing.limits.ts`). ESLint only bans `TODO`, `FIXME` and `XXX` markers and requires comments to be capitalized. The stated rule and the practice disagree. Ask before a large change in either direction.
A module is exactly five files	Five files is the default shape. Several modules have fewer or many more. See Module pattern.
Direct `process.env` access is blocked outside `packages/config`	The `@repo/*` package directories are exempt and read `process.env` directly. `apps/mcp-server` disables the rule in its entry file.
Never swallow an error with an empty catch	Still the rule for a handler’s main job. Best effort side effects deliberately catch, log and continue.
Repositories are the only place that touches Prisma	True for classic modules. Orchestration services (`assistant`, `plan-import`, `forms-ai`), schedulers and `webUserContext` use Prisma directly.

The TypeScript settings, ESM and .js import rule, naming conventions and the layering direction are all still accurate.

`SECURITY.md`

Says	Now
Every request carries a replay protection nonce	Only signed lanes and the bearer lane.
The mobile client attaches replay headers on every call	The trainee lane does not require them.
`/v1/trainee/me` is the only protected route in the trainee lane	See above.
Trainee token is `{ clientId, studioId }`	Plus `preview` and `exp` on preview tokens. A preview token is read only.
All secrets are read through `@perform/config`	Secrets used by `@repo/*` packages (Polar, ZeptoMail, OAuth clients) are read with `process.env` and are not validated at boot.
Service auth fronts `/v1/internal/` and `/v1/web/`	Also `/v1/admin/*`, and `/v1/public/sign` when the request carries `x-service-id`.
The web app calls `POST /v1/internal/studios` when a studio is created	The route exists. `webUserContext` also creates or links the studio on first contact, so a studio appears either way.

The canonical string, the header set, the 5 minute window, the Redis SET NX EX nonce and the timing safe compare are all still accurate. Missing from the file: partner API keys, plan limits, coach permissions, the signing lane throttle and the archived studio checks.

`TESTING.md`

Says	Now
`tests/unit/<module>.test.ts` and `tests/integration/<module>.test.ts`	One flat folder, `apps/core-api/tests/`.
`pnpm test:integration` runs the integration suites	The script references a config file that is not in the repo.
Integration tests run against a disposable Postgres and Redis	No such harness is present. Shell tests stub the routers and use `supertest`.

`ENVIRONMENT.md`

Says	Now
`.env.example` lists every variable	There is no `.env.example` in the working tree.
`OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and storage variables are reserved for upcoming modules and not validated	They are in the Zod schema and in use.
Storage uses `S3_ENDPOINT`, `S3_BUCKET` and so on	core-api uses `R2_`. `@repo/storage` accepts `R2_` with an `S3_*` fallback.
The table of validated variables	Misses about forty: the AI model variables, agent settings, `SESSION_VERIFY_INPROCESS`, `SMARTSEND_OTP_API_KEY`, `TRAINEE_OTP_DEV_MODE`, the app version variables, `APP_WEB_URL`, `WAITLIST_WEBHOOK_URL`, `R2_*`, `AUTOFIT_IMPORT_MASTER_CODE`. See Configuration.
`REDIS_URL` is for BullMQ and real-time fan-out	There is no real-time fan-out. Redis also holds nonces, OTP codes, throttles, AI job state and the seat cache.

`CI_AND_HOOKS.md`

The hook files (.husky/pre-commit, commit-msg, pre-push) and .github/workflows/ci.yml exist as described. The workflows folder also has dev.yml, deploy-do.yml and cve-scheduled.yml, which the note does not mention.

Root `CLAUDE.md` of the workspace

The assistant context file at the workspace root repeats the old picture and has a few extra stale points:

Says	Now
Three repos named `perform-frontend`, `perform-backend`, `perform-mobile`	The folders in the workspace are `frontend`, `backend`, `mobile`.
Local API on port 3031	The schema default for `PORT` is `8000`. The `Dockerfile` exposes `3031`. Set `PORT` to match what the web app’s `CORE_API_URL` points at.
Backend env list with `GREEN_API_*` variables	No `GREEN_API_*` variable is in the config schema.
Every module is exactly five files	See above.
Linting with ESLint and Prettier	Still true for the backend.

​The big change behind most of it

​README.md (docs index)

​ARCHITECTURE.md

​API_CONVENTIONS.md

​ADDING_A_FEATURE.md

​CODING_STANDARDS.md

​SECURITY.md

​TESTING.md

​ENVIRONMENT.md

​CI_AND_HOOKS.md

​Root CLAUDE.md of the workspace