|
|
|
@@ -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`
|