docs: update documentation to OKF v0.1 format

2026-07-21 18:34:42 +00:00
parent 8476e4a59f
commit 09856ccf8e
14 changed files with 563 additions and 16 deletions
@@ -0,0 +1,37 @@
+---
+type: guide
+title: Scoreboard Stream
+description: How live solves are broadcast to the SPA over Server-Sent Events.
+tags: [guide, scoreboard, sse, stream]
+timestamp: 2026-07-21T18:28:00Z
+---
+
+# Endpoint
+
+`GET /api/v1/scoreboard/stream` (`@Sse()` handler in
+`backend/src/modules/system/system.controller.ts`) opens an SSE stream
+that pushes the public scoreboard projection every time a new solve is
+recorded.
+
+# Push path
+
+1. The challenge solve path (admin validation, player submit) updates the
+   `solve` table.
+2. The same code path calls `SseHubService.publish('scoreboard', payload)`
+   (`backend/src/common/services/sse-hub.service.ts`).
+3. Every subscriber to `/api/v1/scoreboard/stream` receives the payload.
+
+The hub is in-process; multi-replica deployments need a shared pub/sub
+to fan out across pods (not in scope for this repo).
+
+# Frontend consumer
+
+The authenticated SPA shell subscribes on mount and updates the scoreboard
+view whenever a new event arrives. The exact rendering lives inside the
+authenticated shell's scoreboard component (see
+[Frontend Structure](/architecture/frontend-structure.md)).
+
+# See also
+
+- [Event Window](/guides/event-window.md)
+- [System Endpoints](/api/system.md)