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

✨ 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

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.
Navigate to backend directory
```
cd backend
```

Create and activate Python virtual environment

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\Scripts\activate

Install Python dependencies
```
pip install -r requirements.txt
```
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
```
Start the backend server
```
python run.py
```
The API will be available at http://localhost:8000

Frontend Setup

Navigate to project root

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

Install npm dependencies
```
npm install
```
Start the development server
```
npm run dev
```
The application will be available at http://localhost:5173
Build for production
```
npm run build
npm run preview
```

⚡ Usage

Starting the Application

Start the backend server (in the backend directory):
```
python run.py
```
Start the frontend (in the project root):
```
npm run dev
```
Open your browser and navigate to http://localhost:5173

Analyzing a Game

Paste or upload a PGN game in the input area
Click "Analyze Game" to start the analysis
Watch real-time progress as each move is evaluated
Navigate through moves using:
- Previous/Next buttons
- Move list sidebar
- First/Last shortcuts
Review classifications for each move and accuracy metrics
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ChessReviewEngine

🔗 Quick Links

📑 Table of Contents

✨ Features

🚀 Installation

Prerequisites

Backend Setup

Frontend Setup

⚡ Usage

Starting the Application

Analyzing a Game

API Examples

Start Analysis (POST)

Get Analysis Results (GET)

WebSocket Connection

Health Check

📂 Folder Structure

🛠 Tech Stack

Languages

Frameworks & Libraries

Build Tools & DevOps

Chess Engines & Libraries

Other Tools

📦 Dependencies & Packages

Frontend Dependencies

Backend Dependencies

🎯 Configuration

Backend Configuration

Classification System

Accuracy Formula

🤝 Contributing

📜 License

🛡 Security

📏 Code of Conduct

🙏 Acknowledgments

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

ChessReviewEngine

🔗 Quick Links

📑 Table of Contents

✨ Features

🚀 Installation

Prerequisites

Backend Setup

Frontend Setup

⚡ Usage

Starting the Application

Analyzing a Game

API Examples

Start Analysis (POST)

Get Analysis Results (GET)

WebSocket Connection

Health Check

📂 Folder Structure

🛠 Tech Stack

Languages

Frameworks & Libraries

Build Tools & DevOps

Chess Engines & Libraries

Other Tools

📦 Dependencies & Packages

Frontend Dependencies

Backend Dependencies

🎯 Configuration

Backend Configuration

Classification System

Accuracy Formula

🤝 Contributing

📜 License

🛡 Security

📏 Code of Conduct

🙏 Acknowledgments