Magnikaru

Magnikaru connects a learned chess position evaluator to a playable browser interface. The model assigns a scalar score to a board; alpha-beta search compares future positions to choose a legal reply. Two Flask services carry the position to the engine and return its move and evaluation to the browser.

My contribution was the frontend, credited in the repository README. The model and training pipeline described here belong to the collaborative project.

How the pieces connect

The frontend template provides a chessboard, an evaluation bar, a move table and game-status text. Its Flask service forwards a FEN position to the model server on port 8900. That server encodes the position into a seven-channel board tensor and 13 game-state features, then uses a four-block Transformer inside a depth-three alpha-beta search.

The response contains a move in Standard Algebraic Notation and a score derived from the evaluation of the submitted position. The committed template references an absent JavaScript file, so the exact browser event handlers and response-to-screen updates cannot be verified from this checkout.

Deployment and service communication

The repository's Dockerfile and Compose file live in Frontend. They package the frontend Flask service in a Python 3.12 Alpine image, set PORT=9000 and publish port 9000. Running docker compose up --build from that directory starts the frontend; ChessServer needs to run separately with its model dependencies and checkpoint on port 8900.

The browser posts its current FEN to the frontend's /api/get_server_move. The frontend makes a synchronous HTTP request to ChessServer's /api/make_move, then relays the returned move and score to the browser. ChessServer reconstructs the board from each FEN rather than keeping a game session for this route.

The model destination is hardcoded to localhost:8900. That works when both Python services run directly on the same host. Inside the frontend container, localhost points back to that container, so reaching a separate model server requires an address change. A two-container setup would use a configurable URL such as http://chessserver:8900/api/make_move on a shared Compose network. That model service is not defined in the committed Compose configuration.

See the frontend deployment configuration and the full deployment discussion in the blog below.

Architecture walkthrough

Read the full blog post: how Magnikaru evaluates a position and chooses its next move. It covers tensor encoding, metadata cross-attention, dataset preparation, the training curriculum, Docker deployment, service networking, move search, the HTTP response and its intended presentation in the application. It also explains the scoring and integration details that need attention when reproducing this revision.

The walkthrough follows repository revision aa60c9b. The trained checkpoint and training CSVs are not included, so the source documents the design without establishing a reproducible playing-strength benchmark.