Building ChessGoddess: Stockfish + LLM on AWS
TL;DR
ChessGoddess analyzes games with Stockfish, explains moves with an LLM, and does image-to-FEN — deployed on AWS ECS. Here is the architecture.
ChessGoddess is an AI chess analysis studio I built that combines Stockfish evaluation with LLM-generated move explanations and image-to-FEN. Upload a PGN; get a move-by-move review with plain-English analysis. Deployed on AWS ECS Fargate via Terraform. This post is the architecture.
What it does
Three workflows in one app:
- PGN analysis — feed a chess game; Stockfish evaluates every move; an LLM explains why the engine prefers what it prefers.
- Image-to-FEN — upload a board photo; computer vision detects the position and outputs the FEN notation.
- Game review — combine the two so a user can analyze a real-world game from a phone photo.
Architecture
| Layer | Tech |
|---|---|
| API gateway | Go + Gin |
| Stockfish runner | Pooled engine processes managed by Go |
| LLM explanations | OpenRouter (cheap models for routine, premium for ambiguous) |
| Image-to-FEN | CV pipeline + classifier |
| Queue | AWS SQS for async analyses |
| Storage | PostgreSQL + Redis |
| Infra | AWS ECS Fargate + Terraform |
Why Stockfish + LLM (not just Stockfish)
Stockfish tells you the best move. It does not tell you why. The why is what users want — what threat does that knight block, what tempo did black lose, why is bishop pair worth half a pawn here.
LLMs are good at narration but bad at chess. Pair them: Stockfish provides the ground truth, the LLM provides the explanation conditioned on the engine eval.
The cheap-LLM trick
Most explanations are routine (knight moves to attack square, defends pawn). Premium LLM calls would burn the budget. We route 80% of explanations through cheap models via openrouter-free-infer and reserve premium calls for positions where the cheap model produces low-confidence output.
Async analysis with SQS
A full PGN analysis takes 30-90 seconds. The API returns immediately with an analysis ID; SQS workers process in the background; the client polls or subscribes via WebSocket.
Microservices as One Engineer covers the broader async pattern.
Image-to-FEN: the hardest part
Real-world chess board photos are noisy: angle, lighting, piece styles. The CV pipeline:
- Detect board boundary (Hough lines + perspective correction)
- Extract 64 cells
- Classify each cell (CNN trained on synthetic + real boards)
- Reconstruct FEN
Accuracy on clean photos: 96%. On phone photos with tilt and shadow: 88%. Good enough; we let users correct ambiguous squares.
Why public source
The whole repo is at github.com/shihabshahrier/ChessGoddess. I open-sourced it because the architecture is more useful as a learning artifact than as a moat — chess analysis is a great teaching example of how to combine deterministic engines with LLMs.
FAQ
Q: What chess engine does ChessGoddess use? A: Stockfish, the open-source chess engine, run as pooled processes managed by Go.
Q: How accurate is image-to-FEN? A: 96% on clean board photos, 88% on phone photos with tilt or shadow.
Q: Is ChessGoddess free? A: The source is open. Hosted analysis is free during beta.
Built by Shihab Shahriar Antor. See my projects and hire me.
Written by
Shihab Shahriar Antor — AI Engineer & Founder of Shahriar Labs. Creator of LetX, QuantumSketch, and more.