Coach web app overview

The coach web app is the Next.js 16 project in frontend/apps/saas. Studio owners and coaches use it to manage trainees, plans, forms, content, tasks and billing. It has no database of its own. Every read and write goes to the core API (the Express service in backend, port 3031 locally). The repo is a pnpm workspace driven by Turborepo. The root package.json is named perform-web.

What the web app owns today

The UI: pages, layouts, client components, design tokens and translations.
A thin server layer: server components that load data, server actions that write, and a handful of route handlers.
Three ways of reaching the core API. See Talking to the core API.

It does not own authentication logic, the oRPC router, Prisma, mail, storage or AI. Those packages were moved into the backend during the server consolidation. The folders are still on disk but are empty apart from leftover node_modules:

Folder	State
`packages/api`	Empty. The oRPC router is served by the core API at `/api/rpc`.
`packages/database`	Empty. No Prisma client in this repo.
`packages/mail`	Empty.
`packages/storage`	Empty.
`packages/ai`	Empty.
`apps/docs`	Empty (only build leftovers).
`apps/mail-preview`	Empty.
`tooling/scripts`	Empty.

frontend/README.md, frontend/docs/README.md and the workspace CLAUDE.md still describe these as live packages, a MySQL database and pnpm db:generate. None of that exists in the code now. See Corrections to older docs.

Folder map

frontend/
├── apps/
│   ├── saas/                 Coach web app (Next.js 16, port 3000)
│   │   ├── app/              App Router tree, colocated feature code, route handlers
│   │   ├── modules/          Cross-route modules (auth, organizations, payments, shared, ...)
│   │   ├── public/           Static files, including the trainee app preview bundle
│   │   ├── tests/            Playwright specs
│   │   ├── proxy.ts          Next.js 16 proxy (the old middleware)
│   │   ├── next.config.ts    Rewrites, redirects, standalone output
│   │   ├── config.ts         App level config (name, themes, redirects)
│   │   ├── vitest.config.ts  Unit test config
│   │   └── playwright.config.ts
│   └── marketing/            Landing page, static export (port 3001 in dev)
├── packages/
│   ├── ui/                   shadcn style components on Radix, `cn`, toasts
│   ├── auth/                 better-auth client, auth feature flags, auth types
│   ├── i18n/                 Locale config and translation JSON files
│   ├── payments/             Plan catalog mirror and purchase helpers
│   ├── notifications/        Notification group catalog for the preferences screen
│   ├── logs/                 consola logger, `logError`, `serializeError`
│   └── utils/                Base URL helpers, `passwordSchema`
├── tooling/
│   ├── tailwind/             `theme.css` design tokens, `tailwind-animate.css`
│   └── typescript/           Shared tsconfig presets
├── tools/
│   ├── check-no-direct-core-api.sh
│   └── check-theme-tokens.mjs
├── deploy/dev/               Release, rollback, health check and prune scripts
├── Dockerfile                Production image (standalone build)
└── .github/workflows/        ci.yml, deploy-do.yml, dev.yml

Inside `apps/saas`

`app/`

The App Router tree. Feature code is colocated with its route: a typical area holds page.tsx (server component), one or more client views, actions.ts (server actions), pure model files and their tests. The full tree is documented in Route tree.

`modules/`

Code shared across routes. Each module has a path alias in tsconfig.json and vitest.config.ts.

Alias	Folder	Contents
`@shared/*`	`modules/shared`	Shell components, hooks, the core API clients, domain types and pure helpers
`@auth/*`	`modules/auth`	Login, signup and password forms, session provider, server session helpers
`@organizations/*`	`modules/organizations`	Active organization provider, member and invitation UI
`@payments/*`	`modules/payments`	Plan picker, billing components, plan limit dialog
`@settings/*`	`modules/settings`	Account settings blocks (name, email, phone, 2FA, sessions)
`@onboarding/*`	`modules/onboarding`	The short account onboarding form
`@admin/*`	`modules/admin`	Super admin lists and the admin API helper
`@i18n/*`	`modules/i18n`	next-intl request config, locale cookie action, `HtmlLocaleSync`
`@config`	`config.ts`	`appName`, themes, redirects, preview URL
`@/*`	`apps/saas`	Anything else, for example `@/modules/sign/...`

modules/sign (the public PDF signing page) has no alias and is imported through @/modules/sign/....

`modules/shared/lib` highlights

File	Purpose
`core-api.ts`	HMAC signed fetch to the core API. Server only.
`perform-api.ts`	`resolveStudioContext` and `performApi` for the `/v1/web` lane
`safe-perform-api.ts`	`ApiResult`, `tryPerformApi`, `tryPerformAll`, `safePerformApi`
`bff-proxy.ts`	Transparent proxy used by the `/api` catch-all route
`bff-server-fetch.ts`	Cookie forwarding fetch for auth reads and a server oRPC client
`orpc-client.ts`, `orpc-query-utils.ts`	Browser oRPC client and its TanStack Query helpers
`orpc-router.generated.d.ts`	Type of the backend oRPC router (generated, lint ignored)
`perform-types.ts`	Hand maintained TypeScript shapes for core API responses
`core-api-routes.ts`, `auth-api-routes.ts`	Path constants
`query-client.ts`, `server.ts`	QueryClient factory and the request cached server instance
`training-schema.ts`, `nutrition-schema.ts`, `form-schema.ts`, `form-conditions.ts`	Content models and normalizers for the builders
`branding.ts`, `studio-appearance.ts`, `studio-settings.ts`	White label theme and studio settings readers
`media-upload.ts`, `media-url.ts`	Browser upload transport and stored media URL resolution

Stack

Concern	Choice
Framework	Next.js 16 App Router, React 19
Language	TypeScript 6, strict
Styling	Tailwind CSS 4, tokens in `tooling/tailwind/theme.css`
Components	Radix primitives through `@repo/ui`, lucide-react icons
Server state	Server components plus server actions. TanStack Query 5 for auth, organizations, purchases and notifications
Typed RPC	oRPC client against the core API `/api/rpc`
Auth	better-auth React client. The server side runs in the core API
Forms	react-hook-form with Zod 4 resolvers
i18n	next-intl 4, cookie based locale, six locales
URL state	nuqs
Drag and drop	dnd-kit
Lint and format	oxlint (type aware) and oxfmt
Tests	Vitest 4 with happy-dom for component tests, Playwright for e2e

Running locally

cd frontend
pnpm install
pnpm dev

pnpm dev first runs ../tools/ensure-core-api.sh --start from the workspace root. That script checks the API’s /healthz endpoint on local port 3031 and starts pnpm dev in backend when the API is not up. Then it starts saas on port 3000 and marketing on port 3001 through Turborepo. Use pnpm dev:app to skip the API check. There is no .env.example in the repo. The root .env currently defines these names:

Variable	Used by
`CORE_API_URL`	Every server side call to the core API
`CORE_API_SERVICE_ID`	`x-service-id` header, defaults to `web`
`SERVICE_AUTH_SECRET`	HMAC signing key shared with the core API
`NEXT_PUBLIC_SAAS_URL`	`getBaseUrl()` in `modules/shared/lib/base-url.ts`
`NEXT_PUBLIC_SITE_URL`	Listed in `turbo.json` `globalEnv`
`NEXT_PUBLIC_MEDIA_CDN_URL`	Base URL for stored media, see `media-url.ts`
`DATABASE_URL`	Not read by any code in this repo. A leftover from the old Prisma package

Optional variables read by the code: AUTH_TRUSTED_ORIGINS (extra dev origins), MARKETING_URL (dev marketing server, default http://localhost:3001), NEXT_PUBLIC_MARKETING_URL, NEXT_PUBLIC_DOCS_URL, NEXT_PUBLIC_TRAINEE_PREVIEW_URL, NEXT_PUBLIC_LANGUAGE_SWITCH_EMAILS, DEPLOYMENT_VERSION and the PRICE_ID_* overrides in packages/payments/config.ts.

Where to go next

Route tree

Every route group, page and what it renders.

Talking to the core API

The proxy, the signed lane, headers and error handling.

Server actions

The read in page, write in action pattern.

Feature areas

Where the code for each product area lives.

​What the web app owns today

​Folder map

​Inside apps/saas

​app/

​modules/

​modules/shared/lib highlights

​Stack

​Running locally

​Where to go next

Route tree

Talking to the core API

Server actions

Feature areas

What the web app owns today

Folder map

Inside `apps/saas`

`app/`

`modules/`

`modules/shared/lib` highlights

Stack

Running locally

Where to go next