Files
CV_Site_Nuxt/OKF_Nuxt/backend-endpoints.md
Noel Sabia 9a4d79a050 feat(ui): update homepage copy and import LinkedIn profile
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.
2026-10-23 22:26:11 +02:00

5.8 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.
api
backend
gateway
contract
frontend
proposal
by at
opencode-go/glm-5.3-flash 2026-10-20T00:00:00Z
by at
human:noel not yet
id resource title
ui-homepage ../../Local_Development/design/homepage/code.html Homepage mockup (data the UI visibly shows)
id resource title
gateway-design ../../OKF_CV_Website/architecture/gateway.md Gateway architecture (sibling bundle, design level)
id resource title
profile-export https://www.linkedin.com/in/noel-sabia-9738a4339/ 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

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, 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.

[
  { "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.

{
  "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