For Developers

A technical guide for contributors to the Chess Analyzer Pro codebase.

Project Overview

Chess Analyzer Pro is a desktop application built with Python and PyQt6. It follows a modular architecture to separate the GUI from the heavy Stockfish analysis logic.

• Stack: Python 3.10+, PyQt6 (GUI), Stockfish (Engine), Google Gemini (AI).
• Repo: imutkarsht/Chess_analyzer

Directory Structure

Chess_analyzer/
├── main.py                 # Entry point - initializes app and splash screen
├── config.json             # User configuration (auto-generated)
├── analysis_cache.db       # SQLite database (auto-generated)
├── requirements.txt        # Python dependencies
├── build.spec              # PyInstaller configuration
│
├── assets/                 # Static resources
│   ├── icons/              # Classification icons (brilliant.svg, blunder.svg, etc.)
│   ├── images/             # Logo, backgrounds
│   ├── pieces/             # Piece themes (cburnett/, merida/, etc.)
│   └── sounds/             # Move sounds (move.mp3, capture.mp3, etc.)
│
├── src/
│   ├── backend/            # Core logic layer
│   │   ├── analyzer.py     # Main analysis engine (~680 lines)
│   │   ├── models.py       # Data structures
│   │   ├── engine.py       # Stockfish wrapper
│   │   ├── pgn_parser.py   # PGN parsing
│   │   ├── game_history.py # SQLite persistence
│   │   ├── cache.py        # Position caching
│   │   ├── book.py         # Opening book
│   │   ├── base_api.py     # Shared API utilities
│   │   ├── chess_com_api.py # Chess.com API
│   │   ├── lichess_api.py  # Lichess API
│   │   └── gemini_service.py # AI integration
│   │
│   ├── gui/                # UI layer (PyQt6)
│   │   ├── main_window.py  # Application window (~720 lines)
│   │   ├── analysis_view.py # Analysis dashboard
│   │   ├── metrics_widget.py # Stats dashboard
│   │   ├── graph_widget.py # Evaluation chart
│   │   ├── styles.py       # QSS styling
│   │   ├── gui_utils.py    # UI helpers
│   │   ├── sidebar.py      # Navigation
│   │   │
│   │   ├── board/          # Board components
│   │   ├── views/          # Main pages (history, settings)
│   │   ├── dialogs/        # Modal dialogs (splash, game picker)
│   │   ├── analysis/       # Analysis widgets (captured, controls)
│   │   ├── components/     # Reusable widgets (stat_card)
│   │   └── metrics/        # Dashboard helpers (charts, workers)
│   │
│   └── utils/              # Utilities
│       ├── config.py       # Config file management
│       ├── logger.py       # Logging setup
│       ├── path_utils.py   # Resource paths
│       └── resources.py    # Asset loading
│
├── tests/                  # pytest suite
└── docs/                   # Documentation

Setup for Development

Prerequisites

• Python 3.10 or higher
• Git
• Stockfish engine

Clone & Install

git clone https://github.com/imutkarsht/Chess_analyzer.git
cd Chess_analyzer

# Create virtual environment
python -m venv venv

# Activate (Windows)
.\venv\Scripts\activate

# Activate (macOS/Linux)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Alternative: Using uv (Faster)

pip install uv
uv venv .venv
.venv\Scripts\activate  # Windows
uv pip install -r requirements.txt

Run Locally

python main.py

[!NOTE] On first run, go to Settings and configure your Stockfish engine path.

Development Guides

Scenario 1: Changing Move Classification Thresholds

To adjust how strict the move classification is:

• File: src/backend/analyzer.py
• Method: _classify_move() (around line 568)
• Action: Adjust the WPL (Win Probability Loss) thresholds:

# Current thresholds in _classify_move():
if wpl >= 0.20:  # 20% → Blunder
elif wpl >= 0.09:  # 9% → Mistake  
elif wpl >= 0.04:  # 4% → Inaccuracy
elif wpl >= 0.01:  # 1% → Good
else:  # <1% → Excellent

Scenario 2: Adding a New Column to Move List

• File: src/gui/analysis_view.py
• Class: MoveListPanel
• Steps:
  1. In __init__, update self.table.setColumnCount(3) to 4.
  2. Add a new header label to the headers list.
  3. In the refresh() method, populate the new column data.

Scenario 3: Adding a New Board Theme

• File: src/gui/styles.py
• Location: BOARD_THEMES dictionary
• Steps:
  1. Add a new entry with light and dark square colors:

     BOARD_THEMES = {
         "default": {"light": "#EEEDD2", "dark": "#769656"},
         "my_theme": {"light": "#F0F0F0", "dark": "#404040"},
         # ...
     }
     

  2. The theme will automatically appear in Settings.

Scenario 4: Adding a New Piece Theme

• Directory: assets/pieces/
• Steps:
  1. Create a new folder with your theme name (e.g., assets/pieces/mytheme/).
  2. Add 12 SVG files named: wK.svg, wQ.svg, wR.svg, wB.svg, wN.svg, wP.svg, bK.svg, bQ.svg, bR.svg, bB.svg, bN.svg, bP.svg.
  3. Update src/gui/board/piece_themes.py to include your theme.

Scenario 5: Adding a New API Integration

• Reference: src/backend/lichess_api.py (or chess_com_api.py)
• Steps:
  1. Create src/backend/your_new_api.py extending BaseChessAPI.
  2. Implement get_user_games() and get_game_by_id() methods.
  3. In src/gui/main_window.py:
     • Import your new API class.
     • Add a new button to the load menu.
     • Connect the action to a handler method.

Scenario 6: Adding a Reusable UI Component

• Directory: src/gui/components/
• Steps:
  1. Create your widget class (e.g., my_widget.py).
  2. Export it in src/gui/components/__init__.py.
  3. Import and use in your views.

Key Files Reference

Testing

We use pytest for stability testing.

# Run all tests
pytest

# Run specific test file
pytest tests/test_game_load.py

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=src

[!IMPORTANT] Always run tests after adding a new feature.

Test Structure

tests/
├── test_game_load.py       # Game loading and parsing tests
├── test_analysis.py        # Analysis engine tests
├── test_api.py             # API integration tests
└── conftest.py             # Shared fixtures

Building for Distribution

To create the ChessAnalyzerPro.exe standalone executable:

# Install PyInstaller if needed
pip install pyinstaller

# Build using the spec file
pyinstaller build.spec

The output will be located in the dist/ directory.

Build Configuration

The build.spec file includes:

• All asset directories (icons, images, pieces, sounds)
• Hidden imports for python-chess and PyQt6
• One-file mode with console disabled
• Custom icon from assets/images/logo.ico

Code Style Guidelines

1. Imports: Group by stdlib → third-party → local, separated by blank lines.
2. Docstrings: Use triple-quoted docstrings for classes and public methods.
3. Type Hints: Use type annotations for function parameters and returns.
4. Signals: Define custom signals at class level with descriptive names.
5. Logging: Use the logger from src.utils.logger for all log output.

Useful Debug Commands

# In any file, add:
from src.utils.logger import logger
logger.debug("My debug message")
logger.info("Info message")
logger.error("Error message", exc_info=True)

# Check logs in: chess_analyzer.log