Theo The Chess Coach

• 

  Chessboard Layout

• 

  Post Game

• 

  Piece Guide

A lot of chess apps either crush you with engine moves or give generic tips that don’t match what you actually did. We wanted something that feels like a real coach: you play, you learn in the moment, and you leave with a few clear takeaways.

Theo plays you at selectable Elo levels. During the game, it can give short, practical hints. After the game, it summarizes the key moments, biggest mistakes, and what to focus on next.

Stockfish is the “truth,” and Theo’s coaching layer is the translator. A FastAPI backend owns the game state, validates moves, and calls Stockfish to generate replies plus analysis (evaluation, principal variation, and top alternatives). We return that as a clean payload for the UI and coaching. Evaluations are provided both in a canonical form and a player-facing form

The hardest parts were keeping the backend fully authoritative (no trusting the client) while still feeling responsive, and shaping raw engine output into something that can be reliably turned into explanations. We also hit some dependency/version friction during frontend setup.

We built an end-to-end pipeline where Stockfish analysis feeds into an LLM that turns engine output into clear, user-friendly coaching. We also wired up the core game loop (create game → submit move → engine reply → return analysis) so the system can play at different skill levels and support either player color.

We learned that the interface matters as much as the model: Stockfish outputs need to be packaged into a clean, consistent schema for an LLM to reliably turn them into coaching. We also learned the value of making the backend the single source of truth for state and legality, which avoids desyncs and makes debugging way easier. Finally, we hit real dependency/version issues on the frontend, which pushed us to lock versions early and keep setup reproducible.

Next we want to take Theo from a finished demo to something people can use every day: smoother onboarding, saved games, and sharing/replay links. We’d also add deeper coaching features like an “explain this move” button, a post-game timeline with key moments, and targeted drills generated from your mistakes.

Built With

• fastapi
• openai
• python
• react
• stockfish
• typescript
• vite