Case study · Live at chess-mate.online
ChessMate: a production chess-coaching platform
Django · Celery + Redis · React · PostgreSQL · Stockfish · AWS Elastic Beanstalk · Sole builder and operator, Jan 2025 - present
Overview
ChessMate imports a player's games from Chess.com or Lichess, analyzes them with Stockfish through an asynchronous pipeline, and turns the results into coaching: single-game feedback and batch reports that find recurring patterns across 5-30 games. It runs in production on AWS with Stripe-backed credits, currently serving 10+ pilot users who have analyzed 100+ batches. I have built and operated every part of it: 818 commits over 18 months.
The product: a batch coaching report generated from 8 analyzed games
Problem
Chess sites show engine evaluations one game at a time. That tells you what went wrong in a single game, but improvement comes from patterns: the same opening mistake, the same endgame weakness, repeated across dozens of games. That is exactly what a human coach charges for. ChessMate's premise: analyze games in bulk and surface those patterns as a prioritized training plan.
What I built
- Game import from Chess.com and Lichess with credit metering (15 free credits on signup, 1 credit per imported game).
- An async analysis pipeline (Celery workers with Redis as broker) running Stockfish at depth 14 with per-game progress tracking across jobs that take 3-5 minutes per game.
- Batch coaching reports: executive summary, top priorities, phase breakdown, opening insights, recurring weaknesses, critical moments, and a 4-week training plan.
- AI-generated coaching narrative across a variety of models, with statistical fallbacks so reports still render when the AI is unavailable.
- JWT auth, rate-limiting middleware, Stripe credit purchases, and shareable read-only report links.
- Operations tooling: management commands for stuck batches and credits, health endpoints, structured logging, Sentry, and an ops runbook.
- 1,700+ automated tests (1,195 backend: 101 standalone plus 1,094 Django, and 579 frontend Jest) gating a GitHub Actions pipeline that tests on Python 3.10/3.11, lints, scans (bandit, gitleaks), and reports coverage to Codecov.
Architecture
Browser
React SPA
ALB
HTTPS
EC2 t3.small
Elastic Beanstalk · single Docker container
RDS PostgreSQL
games, PGN, report JSONB
External APIs
Chess.com / Lichess · OpenAI · Stripe
GitHub Actions: tests + lint + scans → Docker image → EB deploy
The whole platform runs in one Docker container on a single t3.small behind an ALB, with PostgreSQL on RDS. Game PGNs and analysis results live in Postgres (JSONB), not S3: at roughly 6-80 KB per game, storage is negligible and one datastore keeps queries and backups simple.
Two decisions and their tradeoffs
1. Sequential batch analysis on one machine
Stockfish is CPU-bound and shares a t3.small with the web server, so the pipeline runs one game at a time (SEQUENTIAL_BATCH_ANALYSIS, a single worker process). The cost: a 10-game batch takes 30-50 minutes wall-clock and only one batch runs at a time. The gain: no CPU contention with API traffic, predictable memory, and a negligible marginal cost per batch on infrastructure I can run indefinitely. The UI is built around this constraint, with progress tracking per game and honest ETAs, and the documented scaling path (a dedicated worker instance, then parallel workers) waits until real demand exists.
2. Redis inside the app container instead of ElastiCache
Redis serves as both cache and Celery broker, and it runs bundled in the same container as Django, not as a managed ElastiCache cluster. The tradeoff is durability: a redeploy wipes the cache and any queued tasks. I accepted that because the cache is rebuildable, batches are cancelable and retryable by design, and ElastiCache plus the NAT Gateway it pulls in would roughly double the monthly bill at pilot scale. The failure mode this creates is real (it caused the incident below), so the mitigation lives in the job design rather than the infrastructure.
A production failure and the fix
A deploy restarted the single container while a batch was mid-analysis. The in-flight Celery task died with the worker, and the batch record stayed "in progress" forever: no error, no completion, just a report that never arrived. With everything in one container, any deploy could orphan whatever was running.
The fix was to make long-running work bounded, cancelable, and recoverable. Every per-game task now carries soft/hard time limits (840s/900s) so nothing hangs unbounded. A cancel_batch management command marks orphaned batches failed (by batch ID or Celery task ID, with an audit reason), and the ops runbook documents the diagnosis path. On the user side, a "Retry Failed Games" action re-queues only the games that failed, so recovery doesn't need support intervention or re-paying credits.
The takeaway: if your queue and workers can vanish on deploy, that constraint has to be designed into the jobs themselves: time-bound every task, make every job state reachable by ops tooling, and give users a self-serve retry.
Where it stands
- Live in production at chess-mate.online; 10+ pilot users, 100+ batches analyzed.
- 1,700+ automated tests across backend and frontend, run on every push in CI.
- 818 commits over 18 months as the sole builder and operator: code, infra, CI/CD, payments, and on-call. The production repo is private; an earlier public build is on GitHub.
- A written cost-and-scaling analysis maps the path from today's single instance to ~10,000 users, with the first bottlenecks identified (Stockfish CPU, single worker, RDS connections).
Things I can go deep on
- Celery task design: time limits, sequential versus parallel execution, progress tracking, and idempotent retries.
- Capacity and cost modeling: the per-batch cost formulas and what they say about when to scale.
- Cache and broker topology, and what breaks when Redis lives in the app container.
- Stockfish process management: depth, threads, and hash-size tradeoffs against analysis quality and latency.
- Credit ledger integrity across Stripe purchases and refund paths.
- Test strategy at 1,700+ tests: the backend/frontend split, what CI gates, and where coverage actually matters.
- The staged scaling roadmap: rate limits → dedicated worker and managed Redis → multi-instance web tier with WAF.