Skip to main content

Operations Runbook

Safe local startup and the minimum set of checks. This document contains no secrets.

Source document updated 2026-07-21.

Before you start​

  1. Check your branch and uncommitted changes:

    git status --short --branch

  2. Install dependencies from the repository root:

    npm install

  3. Configure the backend environment per Environment. Never add env files to Git.

Local startup​

Run in two terminals:

npm run dev
npm run dev:backend
  • Frontend: http://localhost:5173
  • Backend: http://127.0.0.1:3333
  • Health check: http://127.0.0.1:3333/health

The backend runs through plain Node with no hot reload. After changing backend code, .env, or applying a migration, restart the backend process.

Minimum checks​

npm run build --workspace=frontend
npm run lint --workspace=frontend
npm run i18n:check --workspace=frontend

For the current known results, read docs/HANDOFF.md in the repository — do not assume a command passes just because it was green in the past.

Database and Prisma​

Before any change to the Prisma schema, read Database Migrations.

Critical rules:

  • do not run prisma migrate dev or --create-only against the shared Neon database;
  • do not use prisma db push as a substitute for a production migration;
  • write schema-qualified SQL for the web schema;
  • before applying a migration, confirm the exact target database, the backup/rollback plan, and whether the backend needs a restart.

External integrations​

For any production change, verify that keys, URLs, and webhooks belong to the intended environment. Do not type, print, or commit secrets into documentation or code.

Recovering from a local problem​

  1. Save the error text, without secrets.
  2. Check the backend /health endpoint and the process logs.
  3. Check that the frontend proxy points at the expected backend.
  4. If the problem involves Prisma, stop and consult Database Migrations before running any DB command.
  5. Record the outcome and the next step in docs/HANDOFF.md.