Reaktor RPS Assignment

A web application for viewing Rock-Paper-Scissors match history and player statistics, built as a Reaktor pre-assignment.

What it does

• Matches tab — browse all 184k+ historical matches, filter by date, paginated in batches of 100
• Players tab — search for a player by name, view their full match history filtered by date, sort oldest/newest first
• Leaderboard tab — ranked list of all players by number of wins, filterable by today or a custom date range
• Live updates — new game results appear in real time via Server-Sent Events

Architecture

• Frontend — React + TypeScript + Vite, Material UI
• Backend — Express server that loads all game history from the Reaktor API on startup and caches it in memory. Exposes the cached data via /api/history and proxies the live SSE stream via /api/live.
• State — React Context + useReducer, no external state library
• Deployment — single Railway service; the Express server builds and serves the React frontend as static files

Design decisions

• No database — a database would not meaningfully improve the startup time, since the Reaktor API delivers historical data in a completely unpredictable, non-chronological order. There is no way to detect which records are new without re-fetching and comparing the entire dataset. The tradeoffs are documented in BAD_API_FAULTS.md.
• Server-side caching — all 184k+ games are loaded once on startup and held in memory. Clients poll /api/history every 3 seconds until the load is complete, with a progress bar showing how many games have been loaded.
• Live buffer — live game events received during the initial load are buffered and merged (with deduplication) once history finishes loading.

Project notes for reviewers

The following files are intentionally left in the repository:

• BAD_API_FAULTS.md — analysis of the Reaktor API's faults and limitations
• CONTEXT_HANDOFF.md — session notes documenting key decisions made during development
• CLAUDE.md — the working instructions used with Claude Code (AI assistant) during development

Running locally

1. Create a .env file in the root with your Reaktor API token:

REAKTOR_TOKEN=your_token_here

2. Install dependencies:

npm install

3. Start both the backend and frontend with a single command:

npm run dev

The app will be available at http://localhost:5173.

Testing

npm run test

27 tests covering game logic, state reducer, and leaderboard filtering.