Idempotency is the core invariant
Scoring is the insertion of a Completion row, and it lives in exactly one place. Three things make it exactly-once:
- The whole operation runs in a transaction that re-reads competition state, so a push landing in the same second as the competition closing is correctly rejected once the close transition commits. Reading state before the transaction would leave a window; reading it inside removes one.
- A
@@unique([teamId, challengeId])constraint means a duplicate pass is incapable of double-awarding points, with a Postgres unique-violation guard turning the race into a no-op rather than an error. - Every side effect that follows is idempotent on its own, so a retry repeats it harmlessly.
The same discipline runs through provisioning: an already-ready repository short-circuits, an existing repository is adopted rather than recreated, and re-granting access is a no-op. That is what makes the pg-boss retry policy safe to have at all — a retried job that is not idempotent is just a slower way to corrupt state.
The live leaderboard
Standings are pushed over socket.io, with a Redis adapter so the fan-out survives more than one instance. Handshake authentication reuses the session cookie rather than inventing a second auth path for sockets.
Each competition has two rooms, a public one and an admin one. While the board is frozen, only the admin room receives live updates and the public room keeps the snapshot it was handed on connect — so the freeze is genuinely a freeze for everyone except the organisers, rather than a UI state a determined spectator can see past.
A burst of scores near a deadline is debounced into a single recompute and broadcast. The naive version recomputes the whole board per event, which is exactly the moment it can least afford to.
Wrapped around GitHub
The platform does not host code. A GitHub App creates one private repository per team from a template repository and stamps the challenge slug as an Actions variable. A team pushes; a caller workflow runs the hidden tests, which live in a separate private validator repository so they are never readable from a team repo; GitHub fires a workflow_run event at a single org-level webhook, HMAC-verified, which scores the challenge once and locks the repository.
Teams therefore work in the tool they already use, and the competition inherits GitHub Actions as its test runner instead of the platform owning a sandbox.
Grading options
Set per challenge, by an admin: partial-credit tiers, linear time-decay across the scoring window with a configurable floor, and a first-blood bonus for the first full pass, claimed atomically so two simultaneous passes cannot both win it. A full pass always earns full points even where the tiers stop short, so a team that fixed everything can never be capped below the maximum.
Lifecycle and operations
Competitions move through a timed lifecycle with scheduled state transitions, a freeze snapshot, a winner reveal, and an archive to S3. One image runs the API, the pg-boss workers, and the scheduler, with the worker roles gated behind a flag. Deployment is CloudFormation onto ECS Fargate and Aurora Serverless v2, continuously deployed through GitHub OIDC with no static keys. The environment is validated by zod at boot, so a misconfiguration fails loudly at start rather than quietly at the first request.