Architecture and state model
Boundaries
The website performs server-rendered public/authenticated REST reads through COMPCUBE_INTERNAL_API_URL and browser calls through the public API origin. The reusable client centralizes HTTP and Socket.IO contracts. The plugin uses BeatKhana game authentication, Socket.IO match control, map downloads, local gameplay capture, and replay publishing. PostgreSQL is the authoritative state store.
External dependencies are BeatKhana (OAuth/token signing/linked identity), BeatLeader and ScoreSaber (identity/profile resolution), BeatSaver (map metadata/download), Discord (optional commands), and the replay viewer.
Match state
The active non-final round flow is awaiting_pick → awaiting_scores → round_results → awaiting_pick. Resolving scores creates only the durable results timer. When that timer expires, the backend validates that the referenced round ended with both scores, changes the state to awaiting_pick, and creates a new full-length pick timer. The results display therefore never consumes pick time.
Every material state transition is versioned and audited. Optimistic version checks reject stale writers. PostgreSQL advisory transaction locks serialize queue matching and round score/deadline resolution.
Durable timers
Timers have an absolute due time, type, status, idempotency key, payload, attempts, lease owner/expiry, paused remainder, completion, and last error. A single process avoids overlapping polls; multiple processes compete through conditional database claims. This permits restart recovery and horizontal workers without treating JavaScript timeouts as state.
Historical integrity
Matches retain participants, initial/final MMR, rounds, selected/dealt/discarded/replacement map actions, grouped audit events, raw and calculated score values, health transitions, status history, outcome reason, moderation actions, and undo state. Audit events identify player versus server actions, record timer expiry, and preserve elapsed/remaining time; the detailed per-map rows remain available for integrity checks. Deletion rules protect referenced competitive history while allowing user-owned/transient data to cascade where appropriate.