Skip to main content

API Runbook

Last reviewed: 2026-04-21
Maintained by: Engineering

Purpose​

apps/api is the backend service responsible for auth, business logic, RBAC enforcement, and database access.

Run Locally​

cp .env.example .env
docker compose up -d postgres
pnpm run db:migrate
pnpm run seed:demo
pnpm run dev:api

Expected URL:

  • http://localhost:3000

Key Folders / Where Logic Lives​

  • Routes: apps/api/src/routes
  • Domain services: apps/api/src/features
  • Auth/RBAC middleware: apps/api/src/middlewares
  • DB config + pool: apps/api/src/db
  • Migration scripts: apps/api/src/scripts
  • SQL migrations: database/migrations

Minimum PR Checks​

pnpm run check:api
pnpm run lint:api
pnpm run test:api

If schema changed:

pnpm run db:migrate
pnpm run db:schema:check

How to Debug Startup Failure​

  1. Verify env is loaded and valid:
pnpm --filter @zgrid/api run validate:env
  1. Verify database is reachable on configured host/port:
docker compose ps
  1. Re-run migrations:
pnpm run db:migrate
  1. Start API and inspect first error in terminal:
pnpm run dev:api