3.6 KiB
type, title, description, tags, status, generated, verified, sources
| type | title | description | tags | status | generated | verified | sources | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| API Contract | Backend endpoints the frontend needs | The smallest set of endpoints the Nuxt site needs from the Go gateway, so the backend can be built from this list. |
|
proposal |
|
|
|
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.
{ "status": "stable" }
status: "stable"→ dot green, textSYS_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.
[
{ "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.
statusisactiveorfinished. - 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, sumselfHealedin 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:
202when 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