Operations and troubleshooting
Health
Section titled “Health”GET /api/v1/health— liveness probe (HealthController, throttling skipped). Used by the DockerfileHEALTHCHECK.
Database
Section titled “Database”- Migrations:
npm run backend:migratefrom repo root (Turbo → backendmigration:run). DB_ENABLED=false— backend can run tests or boot without MySQL in some configurations; production must haveDB_ENABLED=trueand valid credentials.
Common issues
Section titled “Common issues”| Symptom | Things to check |
|---|---|
| Browser: CORS errors | CORS_ORIGIN must include the SPA origin (scheme + host + port). |
401 after idle | Access JWT expired; client should refresh via /auth/.../refresh. If refresh fails, re-login. |
403 on admin/vendor APIs | Module guard (modules claim) or store / tenant rule — see Tenancy — stores and outlets. |
| Swagger 404 | SWAGGER_ENABLED=false or wrong path — default UI is /{SWAGGER_PATH} (usually /docs). |
| Static UI shows blank API calls | Production: ensure VITE_API_URL at build time matches how the browser reaches the API, or use empty string for same-origin (Docker default). |
| Terminal webhook rejected | Per-store x-pos-terminal-key — see POS and payment webhooks. |
Organization-specific runbooks
Section titled “Organization-specific runbooks”Add internally: DB failover, external PSP outages, log shipping (e.g. CloudWatch, Datadog), and on-call routing.