Contact bar: Gmail, Heilbronn and a LinkedIn link; the phone chip is removed. Hero: System Architect / Programmer, new pill and quote. Feature cards: humility, learning and helpfulness instead of the infrastructure copy. Terminal: six chapters from the LinkedIn export (PreZero active; Defifort, Alignerr, Outlier, freelance and 42 finished), each with a context label. Rows use a fixed grid so names, context badges, status, uptime and outcome line up vertically; the title bar has red/yellow/green traffic lights and the footer pluralises its counters (1/5/14). OKF: new profile data document for the export and chapter mapping; backend endpoint examples and totals match the real rows.
132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
---
|
|
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)
|
|
- id: profile-export
|
|
resource: https://www.linkedin.com/in/noel-sabia-9738a4339/
|
|
title: LinkedIn profile (exported to Profile.pdf, 2026-10-23)
|
|
---
|
|
|
|
# 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` — the chapter rows
|
|
|
|
The terminal lists one row per life chapter:
|
|
`chapter=… status=… uptime=…% self_healed=…x`.
|
|
|
|
```json
|
|
[
|
|
{ "name": "prezero", "context": "Enterprise", "status": "active", "uptime": 99.98, "selfHealed": 14 },
|
|
{ "name": "defifort", "context": "Web3 startup", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2025" } },
|
|
{ "name": "alignerr", "context": "AI Developer", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2025" } },
|
|
{ "name": "outlier", "context": "AI Developer", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2024" } },
|
|
{ "name": "freelance", "context": "Freelance", "status": "finished", "uptime": 100.0, "outcome": { "label": "completed", "value": "2024" } },
|
|
{ "name": "42-school", "context": "Education", "status": "finished", "uptime": 100.0, "outcome": { "label": "graduated", "value": "2024" } }
|
|
]
|
|
```
|
|
|
|
* One chapter = one row. `status` is `active` or `finished`.
|
|
* `context` is a short display label (`Enterprise`, `Web3 startup`,
|
|
`AI Developer`, `Freelance`, `Education`), not a status and not an
|
|
endpoint.
|
|
* Active chapters map to real workloads; finished ones are history entries.
|
|
* The terminal footer totals come from `GET /api/metrics` below, not
|
|
from counting this response in the browser.
|
|
|
|
## 3. `GET /api/metrics` — the terminal's numbers in one response
|
|
|
|
The homepage terminal shows one row per chapter and a footer with three
|
|
totals. Today the chapter list lives in `app/data/chapters.ts` (from
|
|
`Profile.pdf`), while `uptime` and `rebounds` are still mock values. The
|
|
gateway must own all of it once it exists, because uptime and recovery
|
|
counts are measurements, not copy.
|
|
|
|
```json
|
|
{
|
|
"chapters": [
|
|
{ "name": "prezero", "context": "Enterprise", "status": "active", "uptime": 99.98, "selfHealed": 14 },
|
|
{ "name": "42-school", "context": "Education", "status": "finished", "uptime": 100.0, "outcome": { "label": "graduated", "value": "2024" } }
|
|
],
|
|
"totals": { "active": 1, "sealed": 5, "rebounds": 14 }
|
|
}
|
|
```
|
|
|
|
The array above is abridged; the totals describe all six rows.
|
|
|
|
* `chapters` uses the same row shape as `/api/chapters`. The page maps
|
|
the response into the existing `Chapter` type in one place, so
|
|
`HomeChapterRow` does not know where the data came from.
|
|
* `totals.active`, `totals.sealed` and `totals.rebounds` are computed by
|
|
the gateway from the same rows the response carries. The footer must
|
|
not recompute them client-side, or the rows and the footer can
|
|
disagree after a partial update.
|
|
* `totals.sealed` counts chapters with `status: "finished"`;
|
|
`totals.rebounds` is the sum of `selfHealed`.
|
|
* Finished chapters carry `outcome` (`graduated`, `certified`, …)
|
|
instead of `selfHealed`.
|
|
* Poll it on the same 5-10 s interval as `/api/health`; the SSE stream
|
|
below replaces both later.
|
|
|
|
## 4. `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).
|
|
|
|
## 5. `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/metrics` 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.
|
|
* Per-row presentation (the `chapter=…` labels, colours, the
|
|
`self_healed=Nx` suffix) — the browser formats the numbers the API
|
|
returns; there is no endpoint per field.
|
|
|
|
# Related
|
|
|
|
* Design-level gateway behavior: `OKF_CV_Website/architecture/gateway.md`
|
|
* Trust boundaries and the allowlist: `OKF_CV_Website/architecture/system.md`
|