--- 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) - id: profile-export resource: https://www.linkedin.com/in/noel-sabia-9738a4339/ title: LinkedIn profile (exported to Profile.pdf, 2026-10-23) --- # 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` — the chapter rows The terminal lists one row per life chapter: `chapter=… status=… uptime=…% self_healed=…x`. ```json [ { "name": "prezero", "context": "Enterprise", "status": "active", "uptime": 99.98, "selfHealed": 14 }, { "name": "defifort", "context": "Web3 startup", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2025" } }, { "name": "alignerr", "context": "AI Developer", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2025" } }, { "name": "outlier", "context": "AI Developer", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2024" } }, { "name": "freelance", "context": "Freelance", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2024" } }, { "name": "42-school", "context": "Education", "status": "finished", "uptime": 100.0, "outcome": { "label": "graduated", "value": "2024" } } ] ``` * One chapter = one row. `status` is `active` or `finished`. * `context` is a short display label (`Enterprise`, `Web3 startup`, `AI Developer`, `Freelance`, `Education`), not a status and not an endpoint. * Active chapters map to real workloads; finished ones are history entries. * The terminal footer totals come from `GET /api/metrics` below, not from counting this response in the browser. ## 3. `GET /api/metrics` — the terminal's numbers in one response The homepage terminal shows one row per chapter and a footer with three totals. Today the chapter list lives in `app/data/chapters.ts` (from `Profile.pdf`), while `uptime` and `rebounds` are still mock values. The gateway must own all of it once it exists, because uptime and recovery counts are measurements, not copy. ```json { "chapters": [ { "name": "prezero", "context": "Enterprise", "status": "active", "uptime": 99.98, "selfHealed": 14 }, { "name": "42-school", "context": "Education", "status": "finished", "uptime": 100.0, "outcome": { "label": "graduated", "value": "2024" } } ], "totals": { "active": 1, "sealed": 5, "rebounds": 14 } } ``` The array above is abridged; the totals describe all six rows. * `chapters` uses the same row shape as `/api/chapters`. The page maps the response into the existing `Chapter` type in one place, so `HomeChapterRow` does not know where the data came from. * `totals.active`, `totals.sealed` and `totals.rebounds` are computed by the gateway from the same rows the response carries. The footer must not recompute them client-side, or the rows and the footer can disagree after a partial update. * `totals.sealed` counts chapters with `status: "finished"`; `totals.rebounds` is the sum of `selfHealed`. * Finished chapters carry `outcome` (`graduated`, `certified`, …) instead of `selfHealed`. * Poll it on the same 5-10 s interval as `/api/health`; the SSE stream below replaces both later. ## 4. `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). ## 5. `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/metrics` 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. * Per-row presentation (the `chapter=…` labels, colours, the `self_healed=Nx` suffix) — the browser formats the numbers the API returns; there is no endpoint per field. # Related * Design-level gateway behavior: `OKF_CV_Website/architecture/gateway.md` * Trust boundaries and the allowlist: `OKF_CV_Website/architecture/system.md`