Case study

SpotKick

Real-time PvP penalty duel with commit-reveal

0 duplicatescharges or prizes in tests with lost responses and restartsat-least-once delivery with idempotent consumers (single effect)

Live demo

Play-money demo: fictitious chips, no real money and no prizes. 18+. Play responsibly.

Hosted on my own server: the first load after a quiet period can take a little longer.

What it is and what it solves

A real-time player-versus-player penalty shoot-out: three rounds and sudden death. Both players choose at the same time, so the system must make it impossible to react to the rival's move, survive disconnections and pay each prize once (at-least-once delivery with idempotent consumers, verified in tests).

Business version: SpotKick →

Architecture

SpotKick: architectureWebSocketWebSocketat-least-onceBrowser ANext.jsBrowser BNext.jsAPI instanceNestJS · Socket.IOAPI instanceNestJS · Socket.IORedisqueue · presence · adapterPostgreSQLledger · row locksOutbox workersversioned eventsPlatform Corebatched settle
  • Browser A → API instance (WebSocket)
  • Browser B → API instance (WebSocket)
  • API instance → Redis
  • API instance → Redis
  • API instance → PostgreSQL
  • API instance → PostgreSQL
  • PostgreSQL → Outbox workers
  • Outbox workers → Redis (at-least-once)
  • API instance → Platform Core

Drawn from the architecture diagram in the repository README.

Three technical decisions

  1. Commit-reveal for simultaneous choices

    Each player first sends a hash of the choice plus a random salt, and reveals both only once the two hashes are in, so nobody can pick after seeing the other side's move. If someone does not reveal in time, an auditable fallback choice is applied.

  2. Escrow in a double-entry ledger

    Stakes are locked atomically when the match starts and either paid to the winner or refunded on abandonment, with idempotency keys so a retried request has a single effect: no double charge in tests.

  3. Horizontally scalable rooms

    Several NestJS instances share presence, queues and redacted snapshots through Redis and the Socket.IO Redis adapter, so a player can reconnect to any instance.

Tests, with numbers

  • 200 simultaneous matches and 400 connections without errors, spread across two API instances.
  • Lost responses, restarts and self-exclusion with no duplicated charges or prizes.
  • 14 mutation checks.

Verified

  • Integrated with Platform Core using batched settlement.
  • Solo mode is provably fair: the goalkeeper's zone is derived with HMAC-SHA256 from the server seed, the client seed and a counter, and the server seed is revealed at the end so anyone can verify it.

Not claimed

  • Real-money operation or a third-party audit. All chips are fictitious.
  • Figures come from test runs, not from production traffic.

Stack

  • NestJS 11
  • Socket.IO + Redis
  • Next.js 15
  • React 19
  • Framer Motion
  • PostgreSQL
  • Docker
  • GitHub Actions
  • Vitest
  • Playwright
  • k6