fix production issues

docs/project-design/api-routes.md

@@ -13,19 +13,24 @@ Source of truth for the runtime wiring:
 
 The API is an Express application mounted under `/api/v1` with a few non-versioned utility endpoints:
 
-- `GET /health` returns process health.
+- `GET /health` returns process liveness.
+- `GET /ready` returns readiness (PostgreSQL, Redis, storage). Returns `503` when a dependency fails.
+- `GET /metrics` returns Prometheus-style ops metrics (request counts/latency, outbox gauges).
 - `GET /docs` serves Swagger UI.
 - `GET /api/v1/openapi.json` returns the generated OpenAPI document.
 - `/storage/*` serves uploaded assets such as logos, hero images, vehicle photos, and reservation/customer documents.
 
+A dedicated **`api-worker`** process runs notification outbox dispatch and scheduled jobs (Phase 1). The API process must not embed those jobs when multiple replicas are used (`ENABLE_EMBEDDED_JOBS` stays false). See `docs/design/RUNTIME_AND_OPS_SURFACE.md`.
+
 The app boot sequence in `apps/api/src/app.ts` is intentionally ordered:
 
 1. CORS is applied first.
 2. storage guards are applied before static serving so private customer license files are never anonymously retrievable.
 3. Swagger UI is mounted before Helmet so the UI assets are not blocked by CSP.
 4. webhook routes that require raw payload handling are mounted before `express.json()`.
-5. Helmet, request logging, JSON parsing, and the module routers are mounted.
+5. Helmet, request logging (structured JSON), metrics middleware, JSON parsing, and the module routers are mounted.
 6. the centralized error middleware converts validation, Prisma, and application errors into consistent JSON responses.
+7. Spoofable forwarded headers are scrubbed unless `TRUSTED_FORWARD_HEADERS=true` (see `docs/ops/proxy-trust.md`).
 
 ## Request Lifecycle
 
@@ -382,6 +387,8 @@ Successful route handlers usually return:
 Common deviations:
 
 - `/health`
+- `/ready`
+- `/metrics`
 - `/api/v1/docs`
 - webhook receipt payloads
 - file downloads such as admin invoice PDFs
@@ -393,4 +400,6 @@ There are two documentation layers in the codebase:
 1. runtime API docs from Swagger/OpenAPI at `/docs` and `/api/v1/openapi.json`
 2. this markdown document, which explains design decisions, route grouping, and request flow
 
-The OpenAPI file is useful for request/response contracts, but it is not yet a perfect mirror of every newer route. This document should be updated together with `app.ts`, route files, and the OpenAPI generator whenever route groups change.
+Production-readiness design updates (Phases 0–4) are summarized under `docs/design/`.
+
+The OpenAPI file is useful for request/response contracts. CI enforces a minimum coverage gate via `npm run openapi:coverage`. This document should be updated together with `app.ts`, route files, and the OpenAPI generator whenever route groups change.