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
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:
1 parent
48a403e5ae
commit
15cf091ddf
3 files changed
+93
No files matched your search
@@ -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`
|
||||||
@@ -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.
|
config files — the configs say what, these documents say why.
|
||||||
|
|
||||||
* [Open questions](open-questions.md) - What is still undecided for the Nuxt site.
|
* [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.
|
* [Future updates](future-updates.md) - Pipeline improvement backlog with effort estimates, not yet decided.
|
||||||
* [Update log](log.md) - History of changes to this bundle.
|
* [Update log](log.md) - History of changes to this bundle.
|
||||||
|
|
||||||
|
|||||||
@@ -1,5 +1,8 @@
|
|||||||
# Update Log
|
# 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)
|
## 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.
|
* **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.
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user