From d0c2107efc66ba22067e29207c7fa0f5e432fff4 Mon Sep 17 00:00:00 2001 From: OpenVelo Agent Date: Thu, 23 Jul 2026 05:42:14 +0000 Subject: [PATCH] docs: update documentation to OKF v0.1 format --- docs/api/challenges.md | 13 +++++++++---- docs/guides/scoreboard-page.md | 9 +++++++-- docs/guides/scoreboard-stream.md | 14 ++++++++++---- docs/index.md | 2 +- 4 files changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/api/challenges.md b/docs/api/challenges.md index 14ef80d..a6a80fb 100644 --- a/docs/api/challenges.md +++ b/docs/api/challenges.md @@ -3,7 +3,7 @@ type: api title: Challenges Endpoints description: Authenticated challenge board, single-challenge detail, flag submission, event-state snapshot, and the combined authenticated SSE stream that pushes status + solve frames. tags: [api, challenges, board, score, scoreboard, sse, submit] -timestamp: 2026-07-23T05:10:00Z +timestamp: 2026-07-23T05:41:00Z --- # Endpoints @@ -181,7 +181,7 @@ sources and emits `MessageEvent` frames whose `type` is one of: | `event:` | Payload | |----------|-------------------------------------------------------------------------------------------------| | `status` | `{ state, server_time_utc, event_start_utc, event_end_utc, seconds_to_start, seconds_to_end }` | -| `solve` | `{ challenge_id, player_id, player_name, awarded_points, rank_bonus, awarded_at_utc, position, live_points, solve_count, initial_points, minimum_points, decay_solves }` | +| `solve` | `{ challenge_id, challenge_name, category_abbreviation, player_id, player_name, awarded_points, rank_bonus, awarded_at_utc, position, live_points, solve_count, initial_points, minimum_points, decay_solves }` | Sources: @@ -203,8 +203,13 @@ appended as-is. `backend/src/modules/challenges/dto/challenges.dto.ts`). The controller maps both camelCase and snake_case aliases so a downstream consumer can read either shape (for example -`challenge_id` or `challengeId`, `player_id` or `userId`, -`awarded_points` or `pointsAwarded`). +`challenge_id` or `challengeId`, `challenge_name` or `challengeName`, +`category_abbreviation` or `categoryAbbreviation`, `player_id` or +`userId`, `awarded_points` or `pointsAwarded`). `challenge_name` +and `category_abbreviation` carry the same display metadata that +the `/api/v1/scoreboard/event-log` projection joins in, so the +Scoreboard Event Log tab can render a freshly pushed row without +performing a second lookup. # Scoreboard endpoints diff --git a/docs/guides/scoreboard-page.md b/docs/guides/scoreboard-page.md index 282c157..692b58f 100644 --- a/docs/guides/scoreboard-page.md +++ b/docs/guides/scoreboard-page.md @@ -3,7 +3,7 @@ type: guide title: Scoreboard Page description: How a signed-in player navigates /scoreboard, uses the four tabs (Ranking, Matrix, Event Log, Score Graph), and watches live solve updates arriving over the authenticated SSE stream. tags: [guide, scoreboard, sse, live, ranking, matrix, event-log, score-graph, tester] -timestamp: 2026-07-23T05:10:00Z +timestamp: 2026-07-23T05:41:00Z --- # Overview @@ -157,7 +157,12 @@ The same `solve` frame that lights up the New players are appended to the matrix row list. * **Event Log**: a new `EventLogRow` is prepended to the list (deduplicated by `solveId` so reconnects don't duplicate) and the - list is capped at 200. + list is capped at 200. The SSE solve frame carries + `challenge_name` / `category_abbreviation` (sourced from the same + `challenge` + `category` join that backs the + `/api/v1/scoreboard/event-log` REST projection), so the prepended + row's category abbreviation and challenge name are populated + immediately — no refresh is required. * **Score Graph**: the matching player's series receives a new `{tUtc: awardedAtUtc, value: prevValue + awardedPoints}` point, the series list is re-sorted by final value DESC and trimmed to the diff --git a/docs/guides/scoreboard-stream.md b/docs/guides/scoreboard-stream.md index 20c7af3..1045ecb 100644 --- a/docs/guides/scoreboard-stream.md +++ b/docs/guides/scoreboard-stream.md @@ -3,7 +3,7 @@ type: guide title: Scoreboard Stream description: How fresh solves are broadcast to clients — both the public unauthenticated scoreboard SSE stream and the authenticated combined /api/v1/events stream that the /scoreboard page consumes. tags: [guide, scoreboard, sse, stream, public, authenticated] -timestamp: 2026-07-23T05:10:00Z +timestamp: 2026-07-23T05:41:00Z --- # Overview @@ -43,9 +43,15 @@ is published to the scoreboard hub. * `/api/v1/scoreboard/stream` emits a flattened shape (`challengeId`, `userId`, `pointsAwarded`, `rankBonus`, `solvedAt`) for anonymous spectators. - * `/api/v1/events` emits a richer `SolveEventPayload` (with both - snake_case and camelCase aliases, plus `position`, - `live_points`, `solve_count`, etc.) for the authenticated SPA. + * `/api/v1/events` emits a richer `SolveEventPayload` (with both + snake_case and camelCase aliases, plus `challenge_name`, + `category_abbreviation`, `position`, `live_points`, + `solve_count`, etc.) for the authenticated SPA. The display + metadata fields are sourced from the same `challenge` + + `category` join that backs the `/api/v1/scoreboard/event-log` + REST projection, so the Event Log tab can render an SSE-pushed + row with the challenge name and category abbreviation without a + second lookup. The hub is in-process; multi-replica deployments need a shared pub/sub to fan out across pods (not in scope for this repo). diff --git a/docs/index.md b/docs/index.md index 54b355a..1866336 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ scoreboard, an event window with a public countdown, theming, and admin controls. The docs below are organized by purpose so agents can pull just the slice -they need. Last regenerated 2026-07-23T05:10:00Z. +they need. Last regenerated 2026-07-23T05:41:00Z. # Architecture