--- type: API Contract title: Backend endpoints the frontend needs description: The smallest set of endpoints the Nuxt site needs from the Go gateway, so the backend can be built from this list. tags: [api, backend, gateway, contract, frontend] status: proposal generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-20T00:00:00Z } verified: { by: human:noel, at: not yet } sources: - id: ui-homepage resource: ../../Local_Development/design/homepage/code.html title: Homepage mockup (data the UI visibly shows) - id: gateway-design resource: ../../OKF_CV_Website/architecture/gateway.md title: Gateway architecture (sibling bundle, design level) --- # Decision Nothing decided yet. This is the frontend's wish list: what the UI shows today and later, and the endpoint each dynamic piece needs. Keep it stupid simple: one endpoint per job, plain JSON, no endpoint for data the browser can compute itself. # Endpoints ## 1. `GET /api/health` — footer status dot and `SYS_STABLE` The footer shows a green dot and the text `SYS_STABLE`. The frontend needs one boolean-ish answer: is the system up right now. ```json { "status": "stable" } ``` * `status: "stable"` → dot green, text `SYS_STABLE` * anything else or non-200 → dot grey, text `SYS_DEGRADED` * The gateway computes this from the cluster (are the chapter pods running). * The frontend polls this (mockup says `watch --interval=5s`; 5-10 s is fine). ## 2. `GET /api/chapters` — terminal rows and their footer counters The terminal lists one row per life chapter: `chapter=… status=… uptime=…% self_healed=…x`. ```json [ { "name": "prezero", "status": "active", "uptime": 99.98, "selfHealed": 14 }, { "name": "dreambit", "status": "active", "uptime": 99.95, "selfHealed": 8 }, { "name": "ongoing-studies", "status": "active", "uptime": 99.91, "selfHealed": 5 }, { "name": "42-school", "status": "finished", "uptime": 100.0, "graduated": 2023 }, { "name": "apprenticeship", "status": "finished", "uptime": 100.0, "certified": 2021 } ] ``` * One chapter = one row. `status` is `active` or `finished`. * Active chapters map to real workloads; finished ones are history entries. * "3 Systems Active", "2 Sealed Archetypes", "Cumulative Rebounds: 27" are **not** endpoints: count `status === "active"`, count the finished ones, sum `selfHealed` in the frontend. ## 3. `POST /api/fall/{chapter}` — the knockdown button (later route) The core feature on the life-map page: a visitor presses "push", the chapter pod dies and recovers. * Request: chapter name in the path, checked against an allowlist. * Response: `202` when the fall was triggered; recovery time arrives via the events channel below, not in this response. * Unauthenticated by design, but rate-limited and restricted to the gateway by NetworkPolicy (sibling bundle, trust boundaries). ## 4. `GET /api/events` — live stream (later route, when it hurts) Dev View and live recovery times on the life map need push updates (SSE, per the sibling-bundle design). **Deliberately not in the first version:** polling `/api/health` and `/api/chapters` every few seconds is enough for the homepage; add SSE when the dev view is actually built. # Not endpoints * Hero content (name, quote, contact bar, CV button) — static frontend content. The copy buttons read from local clipboard, no server call. * Aggregated counters (see above) — computed in the browser. # Related * Design-level gateway behavior: `OKF_CV_Website/architecture/gateway.md` * Trust boundaries and the allowlist: `OKF_CV_Website/architecture/system.md`