Chess

A chess application with a custom engine. Play as White against a Python-based engine through a web interface.

Architecture

┌──────────────┐       HTTP        ┌──────────────┐      ┌──────────────┐
│   UI          │ ◄──────────────► │   API         │ ◄──► │   Engine     │
│   Svelte 5    │   localhost:5173  │   FastAPI     │      │   Negamax    │
│   Chessground │   ──────────────► │   Python 3.13 │      │   Alpha-Beta │
└──────────────┘    :8000          └──────────────┘      └──────────────┘

Tech Stack

Component	Stack
Frontend	Svelte 5, Chessground (Lichess board), chess.js, TypeScript, Vite
Backend	FastAPI, python-chess, Pydantic, Python 3.13
Engine	Negamax + alpha-beta pruning, quiescence search, iterative deepening, transposition table, MVV-LVA move ordering, material + piece-square table evaluation

Quickstart

Start both services in separate terminals:

# Terminal 1 — API (localhost:8000)
cd api && ./run.sh

# Terminal 2 — UI (localhost:5173)
cd ui && ./run.sh

See api/README.md and ui/README.md for detailed setup.

Project Structure

chess/
├── api/
│   ├── src/
│   │   ├── main.py              # FastAPI app entry point
│   │   ├── api/
│   │   │   ├── models.py        # Pydantic request/response models
│   │   │   └── routes/
│   │   │       ├── health.py    # Health check endpoint
│   │   │       └── game.py      # Game CRUD + move endpoints
│   │   └── engine/
│   │       ├── eval.py          # Board evaluation (material + PST)
│   │       ├── search.py        # Search algorithm
│   │       └── game.py          # Game state management
│   └── tests/
│       ├── test_eval.py         # Evaluation tests
│       ├── test_search.py       # Search algorithm tests
│       └── test_api.py          # API integration tests
└── ui/
    └── src/
        ├── App.svelte           # Root component (game management, move history, eval bar)
        ├── ChessBoard.svelte    # Interactive board (Chessground wrapper)
        └── lib/
            └── utils.ts         # Chess logic helpers + engine integration

Docker

Docker support is planned. Once added, both services will be available via:

docker compose up

A docker-compose.yml will be added to the project root.