Corrections to older docs

The notes inside the frontend repo were written before the server consolidation and before several UI rebuilds. This page lists what they get wrong. When they disagree with the code, the code wins. Files reviewed: frontend/README.md, frontend/docs/README.md, frontend/docs/COACH_APP.md, frontend/docs/CODING_STANDARDS.md, frontend/docs/CI_AND_HOOKS.md, frontend/docs/DEPLOYMENT.md and the workspace CLAUDE.md.

Architecture

Older docs say	The code today
The frontend owns authentication, organizations and billing	The web app holds only clients. better-auth, the oRPC router and the payment provider code run in the core API
`app/api` holds the better-auth handler	`app/api/[[...rest]]/route.ts` is a transparent proxy to the core API. Auth requests are forwarded, not handled
The core API verifies sessions by calling the web app’s `/api/auth/get-session`	The web app calls the core API for sessions (`fetchAuthApi`)
`packages/api` holds oRPC procedures in `packages/api/modules`	The folder is empty. Procedures live in the backend. The web app has a client and a generated type file
”oRPC + Hono (`packages/api`)“	Same. Not in this repo
Import `db` from `@repo/database`	`packages/database` is empty. Nothing in the web app touches a database
The frontend database is MySQL with the MariaDB adapter (README files), or Postgres on Neon in the `auth` schema (CLAUDE.md, DEPLOYMENT.md)	The web app has no database. `DATABASE_URL` in `.env` and in the build is unused by web code
`packages/mail`, `packages/storage`, `packages/ai`	Empty folders
`apps/docs` (documentation site) and `apps/mail-preview`	Empty folders
`tooling/scripts` (build scripts)	Empty folder
Payments: multi provider (Stripe, LemonSqueezy, Polar, Creem, DodoPayments)	`packages/payments` is a plan catalog and helpers only. Comments in `config.ts` refer to Polar product ids. No provider code is in this repo

Commands and setup

Older docs say	The code today
`cp .env.example .env` or `cp .env.local.example .env`	Neither example file exists in the repo
`pnpm db:generate`, `pnpm db:push`	No such scripts
`pnpm dev` starts the dev server	It first runs `../tools/ensure-core-api.sh --start` and starts the backend when it is not up, then runs `saas` and `marketing`
CI step `pnpm --filter @repo/database run generate`	Not in `ci.yml`
Pre-push runs `format:check`, `lint`, `type-check`, `check:core-api`	Pre-push runs the theme check and oxlint on changed files only
lint-staged has two entries	It has three. The third runs `check-theme-tokens.mjs` on staged source

Locales

Older docs say	The code today
Five locales: he, en, fr, de, es	Six. Arabic (`ar`) is configured and has translation files
Add strings to `en` and `he`	Still the minimum. `ar`, `de`, `es` and `fr` exist and fall back to Hebrew, not English, for missing keys

`COACH_APP.md` says	The code today
`clients/[clientId]` is a four tab client card (`ClientCard.tsx`)	That page is a permanent redirect to the trainee board, `/{slug}/clients?client={id}`. `ClientCard.tsx` no longer exists
A top level `automation` route with trigger and action rules	`/{slug}/automations` is the flow builder. `/workboard/automations` redirects to it. There is no `automation` or `whatsapp` route folder
The dashboard hosts the work inbox with status filters	Tasks live on the work board at `/{slug}/workboard`. `/inbox` still redirects to the studio root
Route list: clients, exercises, foods, templates, forms, automation, calendar, coaches, branding	Add `workboard`, `automations`, `checkin`, `crm`, `content`, `content/home-banner`, `assistant`, and the settings pages `plans`, `notifications`, `integrations`, `autofit`
Sidebar has a “Library” item with a submenu	No Library item. Training and nutrition are two items that open the plan lists. Exercises and foods are reached from there. Settings is the only item with sub items
”The sidebar is always expanded (it is not collapsible)“	It collapses to a 76px rail. The preference is stored in the `perform-nav-collapsed` cookie
`settings/` has general, members, billing	Also plans, notifications, integrations and autofit. General now holds studio feature settings backed by the core API
The org layout fetches the studio with `performApi('/studios/current')` and `parseBranding`	It calls `getStudioAppearance(slug)`, which wraps that and also returns `calendarEnabled`
The org layout prefetches purchases	It prefetches only the active organization. `ActiveOrganizationProvider.setActiveOrganization` prefetches purchases on a switch
”The coach app no longer has a WhatsApp surface”	WhatsApp is back in several places through SmartSend: the chat panel on the trainee board, CRM, work board and check-in review, WhatsApp steps in automation flows, and contact settings
`StudioContext` is `{ studioId, userId, role }`	It also carries `studioName`, `studioSlug`, `userName`, `userEmail`, and `performApi` sends them as headers
A non 2xx response throws	Still true for `performApi`. `tryPerformApi`, `tryPerformAll` and `safePerformApi` now return results, and several actions return `ApiResult` on purpose
Logo upload goes to an `avatars` bucket and is stored as an `/image-proxy/avatars/...` URL	Logos still upload through an oRPC signed URL. `resolveStoredMediaUrl` treats `/image-proxy/avatars/...` as a legacy form and rewrites it to the media CDN

Coding standards

`CODING_STANDARDS.md` or `CLAUDE.md` says	The code today
Prefer `interface` for object shapes	Mixed. `perform-types.ts` uses interfaces. Newer files use `type` freely
”Do not fetch data or hold complex state in client components”	Domain data is loaded on the server, but the large editors hold a lot of client state, and client components call loader actions on demand
Never use relative `../..` imports	Mostly followed through the module aliases. Some route files import siblings relatively, and the trainee program editor page imports the builders with a long relative path
”Use react-icons” (CLAUDE.md) and “Lucide React for icons in the web app” (same file)	lucide-react is the icon set almost everywhere. react-icons is a dependency of `saas` but only four files import it
No shadows in UI	In page containers have none. `DialogContent`, `PopoverContent` and other floating layers do carry a shadow
No comments in code	The code has many explanatory comments, mostly recording why a decision was made
`pnpm check:core-api` enforces the single client rule in CI	The rule the script encodes no longer matches the tree. See below

Deployment

`DEPLOYMENT.md` says	The code today
`dev.yml` triggers on push to `dev`	`dev.yml` is manual only. `deploy-do.yml` runs on push to `dev` and deploys a Docker image
The app deploys as standalone plus PM2	That flow still exists in `dev.yml` and `deploy/dev`. The automatic path is Docker (`Dockerfile`, `deploy-do.yml`)
The workflow pushes the database schema	No workflow touches a database. The same document’s last section already says so
Packaging copies standalone, static, public, deploy scripts	It also copies the marketing export into `public/mkt` and `public/mkt-assets`

Things that look broken or inconsistent in the code

These are not doc errors. They were noticed while reading the code for these pages. None was changed.

The core API boundary check contradicts the code

tools/check-no-direct-core-api.sh fails when any file other than modules/shared/lib/core-api.ts mentions CORE_API_URL. Nine other files do: bff-proxy.ts, bff-server-fetch.ts, modules/admin/lib/admin-api.ts and its test, four api/onboarding/* routes and api/waitlist/route.ts. The script is the first step of ci.yml.

Radix direction is hardcoded to RTL

ClientProviders.tsx renders Direction.Provider dir="rtl" for every locale, while html dir follows the locale.

The notification center is not mounted

Topbar.tsx renders NotificationCenter, but nothing imports Topbar.

The live trainee preview has no consumer

The bundle, the rewrite, the config value, the message constants and the translations exist. No component renders the iframe or requests a preview token.

A damaged .gitignore line

apps/saas/public/trainee-preview/packages/database/prisma/generated/ is two rules joined into one path. It ignores neither.

Three server prefetches are not hydrated

The two billing settings pages and the account security page prefetch into the server QueryClient without their own HydrationBoundary.

Missing translations fall back to Hebrew

About 520 keys are missing from each of ar, de, es and fr, and the fallback locale is he.

Two helpers are both named adminApi

modules/admin/lib/admin-api.ts (cookie forwarded, /api) and modules/shared/lib/admin-api.ts (service signed, /v1/admin) export the same name with different transports.

Leftovers from the starter kit

docker-compose.yml (Postgres and MinIO), provider function types in packages/payments/types.ts, the DATABASE_URL entry in .env, ignorePatterns for Prisma output in the lint and format configs, and a work board header button that still links to the redirected /workboard/automations.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Corrections to older docs

Architecture

Commands and setup

Locales

Routes and navigation

Coding standards

Deployment

Things that look broken or inconsistent in the code

​Architecture

​Commands and setup

​Locales

​Routes and navigation

​Coding standards

​Deployment

​Things that look broken or inconsistent in the code

Architecture

Commands and setup

Locales

Routes and navigation

Coding standards

Deployment

Things that look broken or inconsistent in the code