Files
CV_Site_Nuxt/OKF_Nuxt/backend-endpoints.md
T
Noel Sabia 15cf091ddf
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
docs(okf): add frontend API contract for the gateway
2026-10-20 20:20:32 +02:00

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

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

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