ChessReviewEngine

A full-stack chess game review application with deep engine analysis powered by Stockfish

Analyze chess games with professional-grade move-by-move evaluation, classification, and accuracy metrics - identical in UX and analytical depth to chess.com's Game Review feature.

---

🔗 Quick Links

• 🐛 Report Bug
• 💡 Request Feature
• 📖 View Issues
• 🤝 Contributing Guidelines
• 🛡️ Security Policy

---

📑 Table of Contents

• ✨ Features
• 🚀 Installation
  • Prerequisites
  • Backend Setup
  • Frontend Setup
• ⚡ Usage
  • Starting the Application
  • Analyzing a Game
  • API Examples
• 📂 Folder Structure
• 🛠 Tech Stack
• 📦 Dependencies & Packages
• 🎯 Configuration
• 🤝 Contributing
• 📜 License
• 🛡 Security
• 📏 Code of Conduct

---

✨ Features

• 🎮 PGN Input & Validation - Upload or paste PGN games for comprehensive analysis
• 🔍 Move-by-Move Analysis - Deep engine evaluation for every position in the game
• 🏆 Advanced Move Classification:
  • ✨ Brilliant - Spectacular sacrifices and non-obvious winning moves
  • ✓ Best - Engine's top recommended move
  • Excellent/Great/Good - High-quality moves within acceptable thresholds
  • Mistake/Miss/Blunder - Inaccuracies of varying severity levels
  • Theory - Known opening book moves
• 📊 Accuracy Metrics - Precise player accuracy calculated from centipawn loss
• 🎯 Interactive Chess Board - Navigate through games with visual arrows showing better alternatives
• ⚡ Real-time Progress - WebSocket streaming for live analysis updates
• 🌙 Professional Dark Theme - Polished UI optimized for chess analysis
• 🔄 Smart Engine Integration - Auto-detection of Stockfish installation across platforms

---

🚀 Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.12+ - Download Python
• Node.js 20+ - Download Node.js
• npm (comes with Node.js)
• Stockfish Chess Engine - Download Stockfish

Backend Setup

1. Install Stockfish Engine

   Ubuntu/Debian:

   sudo apt-get update
   sudo apt-get install stockfish

   macOS:

   brew install stockfish

   Windows: Download from https://stockfishchess.org/download/ and add to PATH.

2. Navigate to backend directory

   cd backend

3. Create and activate Python virtual environment

   Linux/macOS:

   python3 -m venv venv
   source venv/bin/activate

   Windows:

   python -m venv venv
   venv\Scripts\activate

4. Install Python dependencies

   pip install -r requirements.txt

5. Configure Stockfish path (optional)

   The application automatically detects Stockfish from system PATH and platform-specific locations. To override, create a .env file in the backend directory:

   STOCKFISH_PATH=/custom/path/to/stockfish
   ENGINE_DEPTH=18
   ENGINE_THREADS=4
   ENGINE_HASH_MB=256

6. Start the backend server

   python run.py

   The API will be available at http://localhost:8000

Frontend Setup

1. Navigate to project root

   cd ..  # if you're in the backend directory

2. Install npm dependencies

   npm install

3. Start the development server

   npm run dev

   The application will be available at http://localhost:5173

4. Build for production

   npm run build
   npm run preview

---

⚡ Usage

Starting the Application

1. Start the backend server (in the backend directory):

   python run.py

2. Start the frontend (in the project root):

   npm run dev

3. Open your browser and navigate to http://localhost:5173

Analyzing a Game

1. Paste or upload a PGN game in the input area
2. Click "Analyze Game" to start the analysis
3. Watch real-time progress as each move is evaluated
4. Navigate through moves using:
   • Previous/Next buttons
   • Move list sidebar
   • First/Last shortcuts
5. Review classifications for each move and accuracy metrics
6. Examine alternative moves shown with arrows for mistakes and blunders

API Examples

Start Analysis (POST)

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "pgn": "1. e4 e5 2. Nf3 Nc6 3. Bb5 a6",
    "engine_depth": 18,
    "time_per_move_ms": 300
  }'

Get Analysis Results (GET)

curl http://localhost:8000/api/game/{task_id}

WebSocket Connection

const ws = new WebSocket('ws://localhost:8000/ws/analyze/{task_id}');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Progress:', data.progress);
};

Health Check

curl http://localhost:8000/api/health

---

📂 Folder Structure

ChessReviewEngine/
├── backend/                      # Python FastAPI backend
│   ├── app/
│   │   ├── api/                  # API route handlers
│   │   ├── engine/               # Stockfish integration & analyzer
│   │   ├── models/               # Pydantic data models
│   │   ├── utils/                # PGN parsing and utilities
│   │   ├── ws/                   # WebSocket connection manager
│   │   ├── config.py             # Application configuration
│   │   └── main.py               # FastAPI application entry
│   ├── requirements.txt          # Python dependencies
│   ├── run.py                    # Backend startup script
│   └── test_*.py                 # Integration and unit tests
├── src/                          # React frontend source
│   ├── api/                      # API client and utilities
│   ├── assets/                   # Static assets
│   ├── components/               # React components
│   ├── types/                    # TypeScript type definitions
│   ├── utils/                    # Frontend utilities
│   ├── App.tsx                   # Main application component
│   ├── main.tsx                  # React entry point
│   └── index.css                 # Global styles
├── public/                       # Static public assets
├── sample_games/                 # Example PGN files
├── .github/                      # GitHub configuration
│   ├── ISSUE_TEMPLATE/           # Issue templates
│   └── pull_request_template.md  # PR template
├── package.json                  # npm dependencies
├── tsconfig.json                 # TypeScript configuration
├── vite.config.ts                # Vite build configuration
├── eslint.config.js              # ESLint configuration
├── postcss.config.js             # PostCSS configuration
├── CONTRIBUTING.md               # Contribution guidelines
├── SECURITY.md                   # Security policy
├── CODE_OF_CONDUCT.md            # Code of conduct
├── LICENSE                       # MIT License
└── README.md                     # This file

---

🛠 Tech Stack

Languages

Frameworks & Libraries

Build Tools & DevOps

Chess Engines & Libraries

Other Tools

---

📦 Dependencies & Packages

Frontend Dependencies

Runtime Dependencies

• react ^19.2.0 - Core React library for building user interfaces
• react-dom ^19.2.0 - React DOM rendering
• chess.js ^1.4.0 - Chess move validation and game state management
• react-chessboard ^5.8.4 - Interactive chess board component
• @tanstack/react-query ^5.90.10 - Powerful asynchronous state management
• react-hot-toast ^2.6.0 - Beautiful toast notifications
• tailwindcss ^4.1.17 - Utility-first CSS framework
• html-to-image ^1.11.13 - Convert DOM to images

Development Dependencies

• typescript ~5.9.3 - TypeScript compiler
• vite ^7.2.2 - Next-generation frontend build tool
• @vitejs/plugin-react ^5.1.0 - Official React plugin for Vite
• eslint ^9.39.1 - Linting utility for JavaScript/TypeScript
• typescript-eslint ^8.46.3 - TypeScript support for ESLint

Backend Dependencies

Python Runtime Dependencies

• fastapi 0.115.6 - Modern, fast web framework for building APIs
• uvicorn[standard] 0.34.0 - Lightning-fast ASGI server
• python-chess 1.999 - Chess library for move generation and validation
• stockfish 3.28.0 - Python wrapper for Stockfish chess engine
• pydantic 2.10.6 - Data validation using Python type hints
• pydantic-settings 2.7.1 - Settings management with Pydantic
• websockets 14.1 - WebSocket protocol implementation
• loguru 0.7.3 - Simplified logging with rich features

---

🎯 Configuration

Backend Configuration

The backend can be configured via environment variables in backend/.env:

# Engine Configuration
STOCKFISH_PATH=/path/to/stockfish    # Auto-detected if not set
ENGINE_DEPTH=18                      # Search depth (1-30)
ENGINE_THREADS=4                     # CPU threads to use
ENGINE_HASH_MB=256                   # Hash table size in MB
TIME_PER_MOVE_MS=300                 # Analysis time per move

# Classification Thresholds (centipawns)
THRESHOLD_BEST=0                     # Exact match with best move
THRESHOLD_EXCELLENT=10               # Within 10 cp
THRESHOLD_GREAT=20                   # Within 20 cp
THRESHOLD_GOOD=40                    # Within 40 cp
THRESHOLD_MISTAKE=100                # 40-100 cp loss
THRESHOLD_MISS=200                   # 100-200 cp loss
THRESHOLD_BLUNDER=300                # 200+ cp loss

# Accuracy Calculation
ACCURACY_K_FACTOR=120                # Exponential decay constant

Classification System

Move classifications are based on centipawn loss:

Classification	Criteria
✨ Brilliant	Best move involving a sacrifice
✓ Best	Exact engine recommendation (0 cp loss)
Excellent	Within 10 cp of best
Great	Within 20 cp of best
Good	Within 40 cp of best
Inaccuracy	40-100 cp loss
Mistake	100-200 cp loss
Blunder	200+ cp loss
Book	Opening theory move

Accuracy Formula

Player accuracy is calculated using exponential decay:

accuracy = 100 × exp(-CPL / K)

Where:

• CPL = Total centipawn loss for all moves
• K = Decay constant (default: 120)

---

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guidelines to get started.

Quick Start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🛡 Security

Security is a top priority. If you discover a security vulnerability, please follow our Security Policy to report it responsibly.

---

📏 Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

---

🙏 Acknowledgments

• Stockfish - World's strongest open-source chess engine
• python-chess - Comprehensive chess library for Python
• react-chessboard - Beautiful React chessboard component
• chess.js - JavaScript chess library for move validation

---

Made with ❤️ by H0NEYP0T-466