docs(okf): add frontend API contract for the gateway
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / ESLint (pull_request) Successful in 38s
PR Check / Typecheck (pull_request) Successful in 44s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 5s
PR Check / Dependency audit (pull_request) Failing after 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
PR Check / AI code review (opencode) (pull_request) Failing after 1m36s

This commit is contained in:
Noel Sabia committed 2026-10-20 20:20:32 +02:00
1 parent 48a403e5ae
commit 15cf091ddf
3 files changed
+93

No files matched your search

+89
View File
@@ -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`
+1
View File
@@ -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.
+3
View File
@@ -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.