API

The contract between the apps and the backend is openapi.yaml (the client API, used by ios/) and openapi-admin.yaml (the admin API, used by dashboard/). They are the source: the backend answers every operation in them, and the iOS and web clients are built against them. These docs link the files as they are. Both are binding (README.md, "Source of truth"); .redocly.yaml holds the lint rules. reference.html renders both with Redoc, in the local docs site (pnpm docs:dev) and the hosted one.

#Rules

• A contract change edits openapi.yaml (or openapi-admin.yaml) in the same PR as the code and is called out in the PR description, with both sides updated. Every track that reads the changed part gets a follow-up task.
• Errors use the ErrorEnvelope schema: a code, a message localized for the request's Accept-Language, whether the client may retry, and the stage. Every request carries Accept-Language: <UI locale> (ADR-001 D13).
• Example responses for the screens live in examples/en/ and examples/zh-Hans/ (served with the design module), one copy per locale (API-shaped seed data behind every number on a board, written by design/tools/build.py). examples/index.json names each file's operation (or request body, or schema), and pnpm design:check (botgumi's botgumi-design check) validates every copy against this contract. ios/scripts/validate_fixtures.py checks the iOS fixtures made from them.
• Fields the screens need but the contract lacks are listed as contract change requests at the top of design/data-binding.md, each with its fallback until merged: CCR-1 to CCR-13 are applied, CCR-14 (error responses on the reads) is open.

#Endpoints

One line per operation lives in the contract itself (operationId, method and path, tags). The screens that call each operation are listed per screen in design/hifi/<ID>/screen.md ("Reads and calls") and in design/flows.md.