Learning Platform Build Note

Building Chess Academy as a classroom-first chess platform

Chess Academy started as a chessboard app idea, but the useful version became broader: local and online play, teacher-led rooms, Stockfish analysis, guided hints, and beginner puzzle modes in one learning surface.

I did not want Chess Academy to be only another chessboard with legal moves. The interesting problem was learning: how a teacher controls a position, how students can safely try ideas, and how analysis can help without taking over the lesson.

That pushed the design toward a single platform with several modes instead of a pile of separate demos. Local play and online rooms give the basic game loop. Teacher-led rooms add a classroom workflow. Analysis and beginner puzzles make the same board useful for explanation and practice.

Teaching needed a different shape

In a normal online chess room, every player interaction is about making a move in the shared game. In a classroom, that is too blunt. Students need a place to try an answer without corrupting the teacher's main line.

So the teaching flow separates the teacher board from student attempts. The teacher can pause the lesson, ask students to try a move, review submissions, and resume the main line. Students get a sandbox during the pause. Their attempts are submitted back for review rather than directly changing the lesson board.

That small boundary changes the feel of the tool. It makes the app safer for classroom use because experimentation is allowed without making the shared position fragile.

Server authority, client reactivity

The real-time layer uses Socket.IO for commands and Yjs for replicated state. The important design choice is that Yjs is not the authority. The server validates moves, owns lesson state, and writes the shared document. Clients observe state and send commands.

That boundary matters for a learning platform. A student should not be able to directly rewrite the teacher's board. A browser glitch should not create a second truth. The server has to be the boring adult in the room.

Analysis that teaches instead of overwhelms

Stockfish is useful, but a raw engine answer is not always a lesson. Chess Academy uses Stockfish for evaluation and best-move guidance while also keeping visual overlays for coverage, attacked squares, defended pieces, and guided hints.

The goal is to help a learner see why a position changes, not just memorize the move the engine prefers. The analysis panel can live beside online rooms, classroom rooms, or solo analysis, so the same explanation tools are reused across contexts.

Beginner puzzles belong in the same product

The beginner modes are local-only by design. They focus on movement patterns, square coverage, and capture geometry without requiring a full game, a server room, or a teacher session.

That keeps the product approachable. Someone can practice how pieces control squares, then move into analysis, then into a classroom session, without switching mental models or tools.

What made deployment interesting

The app runs as a small homelab deployment: a static React client behind Nginx, a Node real-time server, and an Ollama container for optional explanation support. Public access routes through a shared Cloudflare Tunnel, while the LAN fallback stays available for direct checks.

One practical bug came from static asset permissions. Stockfish runs in the browser through worker assets, and Nginx initially returned 403 for the Stockfish script because copied files kept restrictive source permissions. The fix was simple but important: normalize static asset permissions inside the image before serving them.

That is the kind of deployment detail that determines whether an AI feature feels broken or invisible. The browser did not need a new chess engine. It needed the engine file to be readable.

Where it landed

Chess Academy is now a usable chess learning platform: local play, AI play, online rooms, teacher-led rooms, guided analysis, Stockfish hints, and beginner puzzle modes. It is still a lab project, but it has the shape I wanted: a chess tool that treats learning workflows as first-class, not an afterthought.