From 15cf091ddf125d58b23adeafb8ebf2d77fd62c8b Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Tue, 20 Oct 2026 20:20:32 +0200 Subject: [PATCH] docs(okf): add frontend API contract for the gateway --- OKF_Nuxt/backend-endpoints.md | 89 +++++++++++++++++++++++++++++++++++ OKF_Nuxt/index.md | 1 + OKF_Nuxt/log.md | 3 ++ 3 files changed, 93 insertions(+) create mode 100644 OKF_Nuxt/backend-endpoints.md diff --git a/OKF_Nuxt/backend-endpoints.md b/OKF_Nuxt/backend-endpoints.md new file mode 100644 index 0000000..2649937 --- /dev/null +++ b/OKF_Nuxt/backend-endpoints.md @@ -0,0 +1,89 @@ +--- +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` diff --git a/OKF_Nuxt/index.md b/OKF_Nuxt/index.md index 07380cc..ad586d4 100644 --- a/OKF_Nuxt/index.md +++ b/OKF_Nuxt/index.md @@ -9,6 +9,7 @@ released, and what was learned getting there. It is the "why" behind the config files — the configs say what, these documents say why. * [Open questions](open-questions.md) - What is still undecided for the Nuxt site. +* [Backend endpoints](backend-endpoints.md) - The smallest API the frontend needs from the Go gateway: health, chapters, knockdown, events. * [Future updates](future-updates.md) - Pipeline improvement backlog with effort estimates, not yet decided. * [Update log](log.md) - History of changes to this bundle. diff --git a/OKF_Nuxt/log.md b/OKF_Nuxt/log.md index bc0607e..f4ee77a 100644 --- a/OKF_Nuxt/log.md +++ b/OKF_Nuxt/log.md @@ -1,5 +1,8 @@ # Update Log +## 2026-10-20 (frontend API contract) +* **Creation**: Added [backend endpoints](backend-endpoints.md) - the smallest endpoint set the UI needs: `GET /api/health` (footer dot, `SYS_STABLE`), `GET /api/chapters` (terminal rows; counters computed client-side), and the later `POST /api/fall/{chapter}` and SSE `GET /api/events`, with polling-first as the deliberately simple start. + ## 2026-10-19 (pipeline improvement backlog) * **Creation**: Added [future updates](future-updates.md) - five candidate improvements from Anthropic's code-review post (build job, PR intent input, no-repeat re-review, PR template, reviewer eval set), with effort estimates, batching advice for the review budget, and the list of scale-dependent machinery deliberately not adopted.