Local Setup
Everything you need to go from a clean machine to a running PPP stack — frontend at http://localhost:3000, backend tRPC API at http://localhost:4000, talking to the shared dev Postgres — in about 20–30 minutes.
TL;DR
# 1. Prereqs: Node 22+, pnpm 9+, git, openssl
git clone https://github.com/Professional-Performance-Portfolio/ppp.git
cd ppp
pnpm install
pnpm build
# 2. Generate a backend .env with HMAC secrets pre-filled
bash api/backend-ppp/scripts/setup-local-env.sh
# Then edit api/backend-ppp/.env — fill in DATABASE_URL, STRIPE_*, GEMINI_API_KEY,
# AZURE_STORAGE_* from the team (Doppler `ppp/share`).
# 3. Copy the frontend env sample (defaults point at localhost:4000)
cp instances/ppp/.env.sample instances/ppp/.env
# 4. Run both sides — in two terminals
cd api/backend-ppp && pnpm start # :4000
cd instances/ppp && pnpm start # :3000Open http://localhost:3000, log in as admin@sample.com, open the Dashboard. If the CPD tile loads without spinning forever, the frontend, backend, and DB are all wired correctly.
This page is the human getting-started guide. It links out to the authoritative deep-dive docs for each subsystem instead of re-stating them — so when a detail changes, you read it from the source of truth, not a stale copy.
For the full AI / agent convention file (commit style, BDD-first rule, verification gates, no-any policy, etc.) see the root CLAUDE.md. This page deliberately does not duplicate it.
1. Prerequisites
Install these before you clone. Versions matter — older Node or pnpm will fail the pnpm install turbo build step with confusing errors.
| Tool | Version | Why | Install |
|---|---|---|---|
| Node.js | >= 22.14.0 | Enforced by package.json#engines. Turbo + Vite 7 need native fetch. | nodejs.org or nvm install 22 |
| pnpm | >= 9 | Workspace resolver. npm install will not work in this monorepo. | corepack enable && corepack prepare pnpm@latest --activate |
| git | any modern | Obvious. | git-scm.com |
| openssl | any | Used by setup-local-env.sh to generate HMAC token signing secrets. | Pre-installed on macOS/Linux; on Windows use Git Bash or WSL2 |
| GitHub org access | member | The repo is private, and some npm packages come from @moreton-blue-software. You need a read:packages PAT set as NPM_TOKEN for pnpm install to succeed. | Ask Matt for an invite + create a classic PAT with read:packages scope |
| Doppler CLI (optional) | latest | Pulls shared secrets (TEST_DATABASE_URL, Stripe test keys, Gemini, Azure Storage) from the ppp/share config without copy-pasting. | docs.doppler.com/docs/install-cli |
| Azure CLI (optional) | latest | Only needed if you want to read UAT/prod secrets straight from Azure Key Vault (ppp-uk-uat-kv) instead of Doppler. | aka.ms/azcli |
| Docker (optional) | latest | Only needed if you want a throwaway local Postgres instead of sharing the dev DB. The default flow uses the shared dev DB. | docker.com |
| Stripe CLI (optional) | latest | Needed if you are developing payment flows and want to forward webhooks to localhost:4000. | stripe.com/docs/stripe-cli |
Windows users
Use WSL2 or Git Bash for all bash commands on this page. The setup-local-env.sh script uses sed -i and openssl rand -hex, neither of which work in stock PowerShell.
2. Clone and install
git clone https://github.com/Professional-Performance-Portfolio/ppp.git
cd ppp
# Set the npm token for @moreton-blue-software packages
export NPM_TOKEN=ghp_yourTokenHere # or add to ~/.npmrc
pnpm install
pnpm buildWhat pnpm build does: Runs the turbo pipeline — builds every shared package (packages/*, packages-shared/ppp/*), then the two backend apps, then generates the tRPC type bundles consumed by the frontend. You must run this at least once before pnpm start or the frontend will fail to resolve ~ppp-core/* and ~ppp-api/* type imports.
Build shortcuts:
pnpm build # Everything (packages + core + types)
pnpm build:pkgs # Only packages/* (fast path when iterating on a package)
pnpm build:types # Only generated API types
pnpm build:force # Ignore turbo cache — use when a stale cache is lying to youIf a build is misbehaving and you suspect stale cache:
pnpm remove-turbo-cache
pnpm clean # Nuclear: wipes every node_modules and build artifact
pnpm install
pnpm build:force2.1 Git hooks (Husky)
pnpm install installs Husky and wires up the git hooks in .husky/. You do not need to do anything extra — the hooks activate automatically after install.
| Hook | When it runs | What it does |
|---|---|---|
pre-commit | Before every commit | Runs lint-staged (ESLint + Prettier on staged files), spec-drift check, prototype-drift check, test-file naming check for staged *.test.ts files, and feature-graph DAG validation for staged *.feature files. |
pre-push | Before every push | Runs tsc on packages with changed files. If docs/features/*.md is in the push, regenerates and prettier-fixes the derived files (docs/features/README.md, docs/site/features/index.md, docs/site/.vitepress/cache/features-counts.json) and fails the push if they are out of date — prompting you to commit the regen output before retrying. |
post-merge | After every git merge | If docs/features/*.md changed in the merge, re-runs sync-features + prettier on the derived files and shows which files need staging. If pnpm-lock.yaml or package.json changed, reminds you to run pnpm install && pnpm build. |
Bypassing hooks
All hooks check HUSKY=0 first. Prefix any git command with HUSKY=0 to skip all hooks in an emergency:
HUSKY=0 git commit -m "emergency fix"
HUSKY=0 git pushDo not make this a habit — CI is the authoritative gate, but skipping hooks increases round-trip times when CI catches what the hook would have.
Fresh worktrees and node_modules
Hooks that need node_modules (lint-staged, turbo tsc, prettier, tsx) soft-skip with a warning when node_modules is absent. This is normal in a freshly-checked-out worktree — run pnpm install in the worktree root if you want the full fast-fail experience locally.
3. Environment files
There are three .env.sample files to care about. Each lives next to the app that reads it, and each has a slightly different story for how you get real values.
| File | Used by | Fill from |
|---|---|---|
instances/ppp/.env.sample | Vite dev server (frontend) | Copy as-is. Defaults point at http://localhost:4000 for the backend — only edit if you are pointing at UAT instead of local. |
api/backend-ppp/.env.sample | tRPC dev server (backend) | Run bash api/backend-ppp/scripts/setup-local-env.sh once, then fill the REPLACE_ME values from Doppler ppp/share or Azure KV. |
.env.sample (repo root) | Tooling: Grafana, GitHub CLI, npm | Only needed if you are running infra/CI scripts locally. Safe to skip for normal app development. |
3.1 Frontend env — instances/ppp/.env
cp instances/ppp/.env.sample instances/ppp/.envThat's it. The defaults are correct for local development:
| Variable | Default | Meaning |
|---|---|---|
VITE_BETTER_AUTH_BASE_URL | http://localhost:4000/api/auth | Better Auth (session cookies, sign-in, sign-up) endpoint on the local backend |
VITE_APP_TRPC_URL | http://localhost:4000/trpc | tRPC root URL. Change to https://api-uat.professionalperformanceportfolio.com/trpc to point at UAT instead of local backend |
VITE_ALLOWED_HOST | (empty) | Optional Vite allowedHosts entry for tunnel/remote dev (ngrok etc.) |
VITE_FHIR_BASE_URL | https://r4.ontoserver.csiro.au/fhir | CSIRO Ontoserver — SNOMED CT terminology server used by the CPD tagger |
VITE_FHIR_SYSTEM_VERSION | SNOMED CT AU edition, 2025-06-30 | Pins the SNOMED release so procedure codes stay stable between dev and prod |
VITE_OFFLINE_MODE | false | When true, the SPA uses a cached empty response set and skips backend calls entirely |
VITE_DEFAULT_COUNT | 50 | Default page size for paginated lists |
3.2 Backend env — api/backend-ppp/.env
Never hand-edit .env.sample — always work in your own .env. Use the bootstrap script so the three HMAC token signing secrets get auto-generated:
bash api/backend-ppp/scripts/setup-local-env.shThe script:
- Copies
.env.sample→.env(and bails out if.envalready exists, so you never clobber existing secrets). - Runs
openssl rand -hex 32to fillCPD_APPROVAL_SECRET,SECRET_360_KEY, andTIMESHEET_BATCH_SECRET. These are HMAC-SHA256 signing keys, not credentials for any external service — any random string works locally. - Prints a list of the remaining
REPLACE_MElines so you know exactly what is still outstanding.
Then fill in the real values. Every secret's source is named explicitly — no "see the sample file" handwaves:
| Variable | Source | Notes |
|---|---|---|
DATABASE_URL | Ask the team, or doppler secrets get DATABASE_URL --config ppp/dev --plain. For the UAT DB, az keyvault secret show --vault-name ppp-uk-uat-kv --name DATABASE-URL --query value -o tsv | Defaults to the shared dev Postgres. Never point local against UAT/prod for destructive testing. |
TEST_DATABASE_URL | doppler secrets get TEST_DATABASE_URL --config ppp/share --plain | Only used when NODE_ENV=test (i.e. pnpm test). CI overrides this with a local Postgres spun up in GH Actions. |
STORAGE_PROVIDER | Leave as azure-blob | Set to s3 only for the legacy AWS path |
AZURE_STORAGE_ACCOUNT | Doppler ppp/share → AZURE_STORAGE_ACCOUNT — or Azure KV ppp-uk-uat-kv | Profile picture / CV / document uploads fail silently if left as REPLACE_ME |
AZURE_STORAGE_ACCOUNT_KEY | Doppler ppp/share → AZURE_STORAGE_ACCOUNT_KEY | — |
AZURE_STORAGE_CONTAINER | uploads | Matches the UAT container name |
STORAGE_KEY_PREFIX | ppp-dev | Namespaces your local uploads so they do not collide with teammates' |
GEMINI_API_KEY | Doppler ppp/share → GEMINI_API_KEY | Required for the sticker OCR flow in the CPD logger |
STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY | Doppler ppp/share → STRIPE_SECRET_KEY_TEST / STRIPE_PUBLISHABLE_KEY_TEST | Always use test-mode keys locally (sk_test_…, pk_test_…) |
STRIPE_WEBHOOK_SECRET | Run stripe listen --forward-to localhost:4000/webhooks/stripe and copy the whsec_… value it prints | Only needed if you are working on the Stripe webhook handler |
SEND_GRID_API_KEY | Doppler ppp/share → SEND_GRID_API_KEY | Leave as REPLACE_ME if you are not testing email sends — the mailer logs instead |
XERO_CLIENT_ID / XERO_CLIENT_SECRET | Doppler ppp/share — ask before using | Only needed for Xero invoice sync work |
WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET | Doppler ppp/share → WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET | Wellness wearable integration. Redirect URI is http://localhost:3000/wellness/whoop/callback |
FITBIT_CLIENT_ID / FITBIT_CLIENT_SECRET | Doppler ppp/share | Wellness wearable integration |
GOOGLE_FIT_CLIENT_ID / GOOGLE_FIT_CLIENT_SECRET | Doppler ppp/share | Wellness wearable integration |
BETTER_AUTH_BASE_URL | http://localhost:3000 | Leave as localhost for local dev. Set BETTER_AUTH_COOKIE_DOMAIN=.professionalperformanceportfolio.com in UAT/prod only |
WEB_APP_BASE_URL | http://localhost:3000 | Used to build approval/review links inside outgoing emails |
CPD_APPROVAL_SECRET / SECRET_360_KEY / TIMESHEET_BATCH_SECRET | Auto-generated by setup-local-env.sh | HMAC signing secrets for approval-link tokens — never share these between environments |
REDIS_URL | redis://localhost:6379 | Devcontainer ships a redis:7-alpine on this port. Set SKIP_REDIS=1 to disable cache entirely |
For the canonical per-variable reference (including TTLs, secret lineage, and production injection paths) see docs/site/development/backend/environment.md — authoritative for backend env vars.
3.3 Fetching secrets from Azure Key Vault
If you cannot use Doppler, you can pull the UAT secret values directly from Key Vault. You need to be a member of the PPP Azure AD group and logged in via az login:
az login
az account set --subscription <ppp-subscription-id>
# List all secrets in the UAT vault
az keyvault secret list --vault-name ppp-uk-uat-kv -o table
# Read a specific value
az keyvault secret show --vault-name ppp-uk-uat-kv --name DATABASE-URL --query value -o tsv
az keyvault secret show --vault-name ppp-uk-uat-kv --name STRIPE-SECRET-KEY --query value -o tsv
az keyvault secret show --vault-name ppp-uk-uat-kv --name GEMINI-API-KEY --query value -o tsvFull Key Vault inventory, RBAC model, and the rationale for why secrets are injected as Container App env vars (rather than Key Vault references) live in docs/ppp-azure-uat-infrastructure.md — authoritative for Azure secret sourcing.
4. Database
PPP runs on PostgreSQL via Drizzle ORM. For local dev you have two options.
4.1 Option A: Point at the shared dev Postgres (recommended)
Fastest path — no Postgres install, no migrations to run, real seed data (users, hospitals, CPD plan templates) already present. Get the DATABASE_URL value from Doppler ppp/dev and paste into api/backend-ppp/.env. Done.
Be kind to teammates: the dev DB is shared. Do not truncate tables, do not run destructive scripts, and prefix any test data you create with your initials so others can tell it apart.
4.2 Option B: Run Postgres locally in Docker
Useful when you are testing migrations or schema changes and do not want to affect the shared DB.
docker run --name ppp-pg \
-e POSTGRES_USER=ppp \
-e POSTGRES_PASSWORD=ppp \
-e POSTGRES_DB=ppp \
-p 5432:5432 \
-d postgres:16
# In api/backend-ppp/.env:
# DATABASE_URL=postgresql://ppp:ppp@localhost:5432/ppp?sslmode=disableThen run the Drizzle migrations to create the schema:
cd packages-shared/ppp
pnpm db:migrateSeed the admin@sample.com test user (needed to log in at all):
cd api/backend-ppp
INSTANCE_ID=pppDev pnpm tsx scripts/seedAdminUser.tsOptional — seed master data (procedures, hospitals, CPD plan templates, specialties) so the app isn't empty:
cd api/backend-ppp
INSTANCE_ID=pppDev pnpm tsx scripts/seedBootstrap.ts
INSTANCE_ID=pppDev pnpm tsx scripts/seedSettingsData.ts
INSTANCE_ID=pppDev pnpm tsx scripts/seedCpdPlanTemplates.ts4.3 Schema, migrations, and queries
- Drizzle schema:
packages-shared/ppp/src/schema.ts— every column in every PPP table - Zod validators:
packages-shared/ppp/src/zodSchema.ts— runtime validation that mirrors the schema - Migration files:
packages-shared/ppp/drizzle/*.sql— always committed in the same PR as the schema change. Every new migrationNNNN_tag.sqlships with a siblingNNNN_tag.validate.sqlvalidator that runs in CD post-drizzle-kit migrate(see CLAUDE.md "Don't add columns… without a migration" for the full rule) - Ad-hoc SQL debugging: run
pnpm debug __debug__/templates/pg-client-sample.tsfromapi/backend-core/and edit the template file with your query. The fullPgClientdebug pattern is documented inapi/backend-core/CLAUDE.md— authoritative for core DB debugging
5. Running the frontend
cd instances/ppp
pnpm start- Serves on
http://0.0.0.0:3000 - Hot-reloads on file save (Vite HMR)
- Talks to
VITE_APP_TRPC_URL(defaulthttp://localhost:4000/trpc) — so the backend must be running or every page that makes an API call will show a loading spinner forever - To point the frontend at UAT instead of local: set
VITE_APP_TRPC_URL=https://api-uat.professionalperformanceportfolio.com/trpcandVITE_BETTER_AUTH_BASE_URL=https://api-uat.professionalperformanceportfolio.com/api/authininstances/ppp/.env, then restartpnpm start
For the full frontend dev workflow (Storybook, tests with UI, memory-bank conventions), see instances/ppp/README.md and the PPP memory bank — authoritative for frontend dev workflow.
6. Running the backend
cd api/backend-ppp
pnpm start- Serves on
http://localhost:4000 - Health check at
GET /ping— returns200 OKfrom the dev server (createDevServerinapi/backend-core/src/utils/server.ts). The production container entrypoint (api-container.ts) also exposes/healthz, but/healthzis not registered bypnpm start/api-dev.ts - Auto-restarts on file save (tsx watcher)
- Set
DEBUG_LOGS=1to see every tRPC request/response in the terminal
Running in test mode (uses TEST_DATABASE_URL and loads .env.test):
cd api/backend-ppp
pnpm debug # same as pnpm start but with NODE_ENV=test + dotenvxRunning the test suite:
cd api/backend-ppp
pnpm test # one-shot
pnpm test:watch # watch mode
pnpm test:ci # CI mode with coverageBackend test patterns, service-method-vs-tRPC-procedure testing rules, and the createInnerContext helper are all documented in api/backend-ppp/CLAUDE.md — authoritative for backend test patterns and pnpm debug.
7. Authentication locally
PPP uses Better Auth for session management, backed by the PPP Postgres user and session tables. There is no Azure AD B2C in the local flow.
Logging in with the seeded admin
After running the admin seed script (see §4.2) you have an admin@sample.com user with a known password. Use that to log in on the local signup page:
- Open
http://localhost:3000 - Click Sign in
- Email:
admin@sample.com, password:12345Qwerty@(default hard-coded inseedAdminUser.ts). Override withSEED_ADMIN_PASSWORD=… INSTANCE_ID=pppDev pnpm tsx scripts/seedAdminUser.tsif you need a custom one — never use this account against UAT or production.
Cookie behaviour
Better Auth sets an HTTP-only better-auth.session-token cookie scoped to localhost. In local dev, BETTER_AUTH_COOKIE_DOMAIN must be unset so the cookie defaults to the current host. In UAT/prod it is set to .professionalperformanceportfolio.com so the API (api-uat.…) and the frontend (ppp-uat.…) share a session across subdomains.
If your session "logs you out on every request": confirm BETTER_AUTH_COOKIE_DOMAIN is unset in your local .env and that you are hitting the app via http://localhost:3000 (not 127.0.0.1).
Test accounts in UAT
If you need to sign in against UAT with known test personas (e.g. for e2e reproduction), the full list of seeded test accounts is in docs/site/development/test-accounts.md.
8. Golden-path verification
Run this exact flow after your first setup. If every step works, your frontend, backend, and database are all wired up correctly.
- Backend is alive. In one terminal:
cd api/backend-ppp && pnpm start. In another:curl http://localhost:4000/ping— expect a200response. (/healthzonly exists in the production container entrypoint, not the dev server.) - Frontend is alive.
cd instances/ppp && pnpm start. Openhttp://localhost:3000— expect the PPP marketing/landing or sign-in screen without a "Failed to fetch" banner. - Sign in works. Sign in as
admin@sample.com. You should land on the Dashboard without being bounced back to the sign-in page. If you bounce: see §7 (cookie domain) and §9 (port conflicts). - tRPC round-trip works. On the Dashboard, the CPD tile should populate with plan data. Watch the backend terminal — you should see a
trpc.ppp.getCurrentUserand one or moretrpc.ppp.cpd.*calls logged. This proves frontend → backend → Postgres is connected end-to-end. - Write path works. Navigate to CPD → My Plan, click Add Activity, fill in a placeholder activity, save. The activity should appear in the list immediately. In the DB,
SELECT * FROM ppp_activity ORDER BY "createdAt" DESC LIMIT 1;should show your new row.
If step 4 or 5 fails, the DB credentials in api/backend-ppp/.env are almost certainly wrong — double-check DATABASE_URL by running psql "$DATABASE_URL" -c 'SELECT now();'.
9. Common problems
The top gotchas, in order of how often they bite new engineers.
9.1 "Cannot find module ~ppp-core/…" on frontend start
Symptom: Vite fails to import tRPC types. Frontend does not start or shows a red overlay.
Cause: You ran pnpm start before pnpm build. The frontend imports generated types from the shared packages and they don't exist yet.
Fix:
pnpm build # From repo root
# Then retry pnpm start in instances/ppp9.2 pnpm install fails with 401 / 403 on @moreton-blue-software/*
Symptom: npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/...
Cause: No NPM_TOKEN, or the PAT does not have read:packages scope, or the GitHub account behind the PAT is not a member of @moreton-blue-software.
Fix: Create a classic PAT at github.com/settings/tokens with read:packages scope, export it: export NPM_TOKEN=ghp_…, then re-run pnpm install. Or add //npm.pkg.github.com/:_authToken=ghp_… to ~/.npmrc.
9.3 "Wrong Node version" or weird turbo crash
Symptom: Error: Cannot read properties of undefined (reading 'startsWith') deep in a node_modules bin, or turbo segfaults during build.
Cause: You are on Node < 22. Check with node --version.
Fix:
nvm install 22
nvm use 22
pnpm clean && pnpm install && pnpm build:force9.4 Frontend loads but every API call hangs
Symptom: Dashboard shows a spinner forever. Network tab shows pending POST /trpc/… requests.
Cause: The backend isn't running, or you changed VITE_APP_TRPC_URL to a non-reachable URL, or something else is bound to port 4000.
Fix:
# Is the backend up?
curl http://localhost:4000/healthz
# Is port 4000 bound by the right process?
lsof -iTCP:4000 -sTCP:LISTEN # macOS/Linux
netstat -ano | findstr :4000 # Windows
# If port is bound by an orphan process, kill it and restart the backend9.5 Backend throws "CPD_APPROVAL_SECRET is not set" on startup
Symptom: Backend process exits immediately with a thrown Error about CPD_APPROVAL_SECRET, SECRET_360_KEY, or TIMESHEET_BATCH_SECRET.
Cause: You copied .env.sample manually instead of running setup-local-env.sh, so the three HMAC secrets are still REPLACE_ME.
Fix:
rm api/backend-ppp/.env
bash api/backend-ppp/scripts/setup-local-env.shThe script regenerates the secrets with openssl rand -hex 32. Then re-fill the external-service REPLACE_ME values you had before.
9.6 Stale turbo cache / "I know I fixed this"
Symptom: A change you know you made has no effect. A package seems to be rebuilt from a previous version.
Cause: Turbo is serving a cached build from before your change. Happens most often after rebases or when a generated file changes.
Fix:
pnpm remove-turbo-cache
pnpm build:forceIf that still doesn't work, the nuclear option is pnpm clean && pnpm install && pnpm build:force.
9.7 "Relation does not exist" or "column does not exist" from backend
Symptom: Any tRPC call that hits a given table returns a Postgres error about a missing table or column.
Cause: Drizzle schema has a column that the database does not. Either you are pointing at a DB that has not had recent migrations applied, or a teammate's PR added a column without shipping the migration file (this caused incident #4379 — that's why CI now has a migration-check gate).
Fix: If you are on the shared dev DB, pull origin/uat and pnpm install — migrations run automatically in dev. If you are on a local Docker Postgres, cd packages-shared/ppp && pnpm db:migrate. If the problem is your own PR, run cd packages-shared/ppp && pnpm db:generate and commit the generated drizzle/NNNN_tag.sql + sibling .validate.sql file alongside your schema change.
9.8 Key Vault access denied
Symptom: az keyvault secret show returns 403 Forbidden.
Cause: You are logged in with az login but your account is not a member of the PPP Azure AD group that has Key Vault Secrets User role on ppp-uk-uat-kv.
Fix: Ask Matt to add you to the group. As a stopgap, get the secret value from a teammate via Doppler instead.
10. Verification before calling it done
CLAUDE.md defines the mandatory verification gates that map 1:1 to CI Tier 1. Run the ones that match your change before you push:
| Changed area | Commands |
|---|---|
api/backend-ppp/ | cd api/backend-ppp && pnpm tsc && pnpm lint && pnpm lint:no-console |
instances/ppp/ | cd instances/ppp && npx tsc --noEmit -p tsconfig-lint.json && pnpm lint && pnpm lint:no-console |
packages-shared/ppp/ | pnpm tsc (from root) |
| Any of the above | node .github/scripts/check-no-any.mjs (no-explicit-any gate) |
| Any backend test files | cd api/backend-ppp && npx tsc --noEmit -p tsconfig.test.json |
The full verification checklist — including BDD-first rule, no-any policy, and the migration + validator gate — lives in CLAUDE.md under Verify Before Done.
11. What to read next
CLAUDE.md— the canonical agent / developer convention file (workflow rules, verification gates, BDD-first rule, no-anypolicy, git worktree policy, import aliases)instances/ppp/README.mdandinstances/ppp/memory-bank/— frontend-specific dev workflow, PLAN vs ACT mode, component checklistapi/backend-ppp/CLAUDE.md— tRPC test patterns,pnpm debugmode, service-method-vs-procedure testingapi/backend-core/CLAUDE.md— database debugging viaPgClient, role-based filtering, ad-hoc SQL templatedocs/site/development/backend/environment.md— the authoritative per-variable backend env referencedocs/ppp-azure-uat-infrastructure.md— Azure Key Vault inventory, cost breakdown, Container App config, secret lineage from Doppler → Pulumi → env var- Feature specs — acceptance criteria and status for every named feature
- System overview — high-level data flow with Mermaid diagrams
- Developer conventions — coding standards, git workflow, project conventions
- Code standards — type safety, code quality rules
- Backend testing and Frontend testing — test layer guides
Contributions
Spot something wrong or out of date on this page? Edit docs/site/development/local-setup.md and open a PR against uat. Keep the cross-links pointing at the canonical sources — this page is a map, not a mirror.