Repositories and workspace

Workspace layout

The workspace root is a plain folder, not a Git repository. Each surface is its own nested Git clone, checked out on the dev branch.

perform-project/
├── backend/        nested clone, branch dev   (core API)
├── frontend/       nested clone, branch dev   (coach web app)
├── mobile/         nested clone, branch dev   (trainee app)
├── docs/           nested clone               (this documentation site)
├── tools/
│   ├── ensure-core-api.sh
│   └── wait-for-api.sh
├── package.json    root scripts only
└── README.md

Run Git, installs, tests and commits inside the repository that owns the file. Nothing at the root is committed with the application code. The root package.json only exists to start the API and the web app together:

Script	What it runs
`pnpm dev`	`concurrently` runs `dev:api` and `dev:web` and stops both when one exits.
`pnpm dev:api`	`pnpm -C backend dev:api`
`pnpm dev:web`	`tools/wait-for-api.sh`, then `pnpm -C frontend dev`

tools/wait-for-api.sh polls http://127.0.0.1:3031/healthz for up to 90 seconds. tools/ensure-core-api.sh does the same check and, with --start, launches pnpm dev in backend in the background and writes its output to a log file in /tmp.

backend

A pnpm workspace built with Turborepo. Workspace globs are apps/* and packages/*.

backend/
├── apps/
│   ├── core-api/                 the Express service
│   │   ├── src/
│   │   │   ├── server.ts         bootstrap, AppContext, workers, shutdown
│   │   │   ├── app.ts            middleware stack and mounts
│   │   │   ├── config.ts         Zod env schema
│   │   │   ├── context.ts        AppContext type
│   │   │   ├── health-checks.ts  readiness checks
│   │   │   ├── middleware/       auth, trainee-auth, web-context, hono-gateway, rate-limit, require-role, coach-access
│   │   │   ├── modules/          one folder per domain module, registered in modules/index.ts
│   │   │   ├── workers/          BullMQ workers and schedulers
│   │   │   ├── ai/               nutrition analysis, form summaries, program and recipe generation
│   │   │   ├── integrations/     external catalog clients
│   │   │   ├── storage/          R2 client and HEIC handling
│   │   │   ├── lib/              push, phone, timezone helpers
│   │   │   └── scripts/          one-off import and backfill scripts
│   │   └── tests/                Vitest files
│   └── mcp-server/               stdio MCP server published as the perform-mcp binary
├── packages/
│   ├── config/         defineEnv: loads dotenv and validates a Zod schema
│   ├── db/             @perform/db: migration schema, migrations, seed. Re-exports the client from @repo/database
│   ├── database/       @repo/database: merged auth and public schema, generated client, Zod types, query helpers
│   ├── api/            @repo/api: the Hono and oRPC app mounted under /api
│   ├── auth/           @repo/auth: better-auth server config and plugins
│   ├── payments/       @repo/payments: Polar and Stripe providers, plans, webhook handler
│   ├── mail/           @repo/mail: React Email templates and mail providers
│   ├── storage/        @repo/storage: S3-compatible signed URLs
│   ├── notifications/  @repo/notifications: in-app notification catalog
│   ├── i18n/           @repo/i18n: translations used by server-side email copy
│   ├── logs/           @repo/logs: consola logger used by the ported packages
│   ├── utils/          @repo/utils: base URL and trusted origin helpers
│   ├── errors/         @perform/errors: AppError, ErrorCode, error middleware
│   ├── logger/         @perform/logger: pino logger and pino-http middleware
│   ├── observability/  @perform/observability: request id, health, readiness, metrics
│   ├── queue/          @perform/queue: BullMQ factory and queue names
│   ├── security/       @perform/security: HMAC service auth, replay protection, nonce store
│   ├── smartsend/      @perform/smartsend: WhatsApp API client
│   ├── mcp-tools/      @perform/mcp-tools: tool definitions shared by /mcp and the stdio server
│   └── types/          @perform/types: response envelope, roles, shared types
├── deploy/dev/         release.sh, rollback.sh, health-check.sh, prune.sh
├── docs/               internal notes (some are stale, check the code)
├── scripts/            repository-level one-off scripts
├── tools/              check-em-dash.sh, check-em-dash-staged.sh, check-cves.sh
├── Dockerfile
├── ecosystem.config.cjs
├── eslint.config.mjs
├── tsconfig.base.json
└── turbo.json

Two package scopes exist for a historical reason. @perform/* packages were written for the backend. @repo/* packages were ported from the web repository during the server consolidation and keep their original scope and code style. tsconfig.base.json maps @perform/* to packages/*/src/index.ts, so the API type-checks against package source. The @repo/* packages are consumed through their built dist output. That difference is the cause of the stale dist problem described in Troubleshooting. Domain modules follow a five-file pattern: <name>.routes.ts, <name>.controller.ts, <name>.service.ts, <name>.repository.ts and <name>.schema.ts.

frontend

A pnpm workspace built with Turborepo. Workspace globs are apps/*, packages/* and tooling/*. Shared dependency versions live in the catalog block of pnpm-workspace.yaml.

frontend/
├── apps/
│   ├── saas/                     the coach web app
│   │   ├── app/
│   │   │   ├── (authenticated)/  signed-in routes, organization routes under [organizationSlug]
│   │   │   ├── (unauthenticated)/ login, signup and related routes
│   │   │   └── api/              the [[...rest]] proxy plus a few route handlers (forms, sign, onboarding, waitlist, workboard, content upload)
│   │   ├── modules/              admin, auth, i18n, onboarding, organizations, payments, settings, shared, sign
│   │   ├── public/               includes mkt (marketing export) and trainee-preview (mobile web export)
│   │   ├── proxy.ts              Next.js 16 proxy (the former middleware)
│   │   ├── next.config.ts
│   │   ├── vitest.config.ts
│   │   └── playwright.config.ts
│   └── marketing/                landing page, built as a static export with assetPrefix /mkt
├── packages/
│   ├── ui/             shadcn and Radix components
│   ├── auth/           better-auth client, config, helpers and types
│   ├── payments/       client-safe plan config and helpers
│   ├── notifications/  notification catalog
│   ├── i18n/           next-intl config and translations (ar, de, en, es, fr, he)
│   ├── logs/
│   └── utils/
├── tooling/
│   ├── tailwind/       shared Tailwind 4 theme
│   ├── typescript/     shared tsconfig presets
│   └── scripts/
├── tools/              check-no-direct-core-api.sh, check-theme-tokens.mjs
├── deploy/dev/         release.sh, rollback.sh, health-check.sh, prune.sh
├── Dockerfile
├── docker-compose.yml  local Postgres and MinIO, left from the starter kit
├── ecosystem.config.cjs
└── turbo.json

The folders apps/docs, apps/mail-preview, packages/api, packages/database, packages/ai, packages/mail and packages/storage still exist on disk in some checkouts but contain only a leftover node_modules folder. They have no package.json and are not part of the workspace. The code they held now lives in the backend.

apps/saas/tsconfig.json defines the path aliases: @/* for the app root, and @shared/*, @auth/*, @organizations/*, @payments/*, @settings/*, @admin/*, @onboarding/*, @i18n/* and @config for the feature modules.

mobile

A single Expo package managed with pnpm. It has no Turborepo setup.

mobile/
├── src/
│   ├── app/              Expo Router routes: (auth), (app), (app)/(tabs), choose-studio
│   ├── features/         app-update, auth, branding, calendar, content, food-preferences, forms, health,
│   │                     home, movement, notification-preferences, nutrition, onboarding, plans, profile,
│   │                     progress, share-story, shopping, tracking, workouts
│   ├── components/       shared UI primitives
│   ├── lib/              api client, i18n, storage, media, notifications, rtl, time
│   ├── theme/            design tokens
│   ├── constants/
│   └── types/
├── modules/
│   └── cardio-notification/   local Android native module
├── plugins/              Expo config plugins for Health Connect
├── patches/              pnpm patches for four dependencies
├── scripts/              OTA scripts, preview export, node:test files
├── assets/
├── app.json              Expo config
├── app.config.js         overrides used by the web preview export
├── eas.json              EAS build and submit profiles
└── .nvmrc                24.14.0

The android and ios folders are generated by expo prebuild and are not the source of truth. Native configuration lives in app.json, the config plugins and the local module.

Where the same logic lives twice

Some rules are implemented in more than one repository and must be changed together. Search for the function name in all three repositories before changing one of these:

Form field conditions: backend/apps/core-api/src/modules/forms/form-conditions.ts, frontend/apps/saas/modules/shared/lib/form-conditions.ts, and the forms feature in mobile/src/features/forms/lib.
MBP portion math: backend/apps/core-api/src/modules/foods/mbp.ts, frontend/apps/saas/modules/shared/lib/mbp.ts and mobile/src/features/nutrition/lib/mbp.ts.
Workout time estimates: mobile/src/features/workouts/lib/estimateWorkout.ts and the trainee service in the backend.

This list is not complete. When a rule produces a number or a visibility decision that both a coach and a trainee see, assume it has a twin.

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

Repositories and workspace

Workspace layout

backend

frontend

mobile

Where the same logic lives twice

​Workspace layout

​backend

​frontend

​mobile

​Where the same logic lives twice

Workspace layout

backend

frontend

mobile

Where the same logic lives twice