API and data
The OpenAPI specs are the source of truth for behaviour, and the SQL migrations are the source of truth for shape. Neither is generated from the other.
| Page | Read it when |
|---|---|
| API standards | You are adding or changing an endpoint and need the house rules. |
| Curl examples | You want a runnable request for every operation. Generated — do not edit. |
| Contracts | You need the payload contracts that cross service boundaries on Redis Streams. |
| API versioning | You are about to change something already shipped under /api/v1, which is frozen. |
| Schema audit | You want optional and nullable reported separately across the aggregate spec. Generated. |
| Migrations | You are writing a migration pair under services/<name>/migrations/. |
| Data engineering | You need the operational contract for the auth, users, rbac, and audit schemas. |
| Data reference | You want to know which schema owns what, and who may write to it. |
| Data audit | You are reviewing schema findings. Generated by go run ./cmd/dbdocs. |
| Data schema | You want the live table and column listing. Generated — do not edit. |
| Upgrade guide | You are moving an existing deployment to a newer release. |
Spec first, always
Behaviour absent from services/<name>/openapi.yaml does not exist. Edit the spec, then run make contracts SVC=<name>; the generated gen/ directory is committed and CI fails when it drifts.
The gateway builds a fail-closed route registry from every service spec at boot. An unknown permission refuses boot and an unknown route returns 404, so a new endpoint is unreachable until its spec says who may call it.