Architecture

Chess Analyzer Pro follows a decoupled Model-View-Controller pattern, separating chess computation and data handling from the PyQt6 user interface.

Design Overview

┌─────────────────────────────────────────────────────────┐
│                    PyQt6 GUI Views                       │
│  (analysis, explorer, history, stats, settings, etc.)   │
└──────────────────────────┬──────────────────────────────┘
                           │ Qt Signals / Slots
┌──────────────────────────▼──────────────────────────────┐
│               MainWindow (Controller)                    │
│         Orchestrates views, workers, and state           │
└──────────┬──────────────┬──────────────┬────────────────┘
           │              │              │
    ┌──────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
    │  Workers    │ │  Engine  │ │   Storage   │
    │  (QThread)  │ │ (UCI)    │ │  (SQLite)   │
    └─────────────┘ └──────────┘ └─────────────┘

Model (src/backend/): Stateless libraries for PGN parsing, UCI engine communication, API clients, and LLM services
View (src/gui/): Pure layout components using PyQt6 widgets styled with QSS. Views never block on network or engine calls
Controller (src/gui/main_window.py): Custom QThread instances run blocking operations asynchronously and emit signals back to the UI

Directory Layout

src/
├── main.py                     # Application entry point
├── constants.py                # App-wide constants
│
├── backend/
│   ├── analysis/
│   │   ├── analyzer.py         # Game analysis orchestrator
│   │   ├── engine.py           # Stockfish process manager (UCI)
│   │   ├── local_book.py       # SQLite opening book traversal
│   │   ├── math_utils.py       # Win probability, accuracy formulas
│   │   ├── move_classifier.py  # Move classification heuristics
│   │   ├── opening_db.py       # Opening database from TSV
│   │   └── polyglot_book.py    # Polyglot .bin file support
│   ├── api/
│   │   ├── base_api.py         # Shared HTTP client
│   │   ├── chess_com_api.py    # Chess.com API integration
│   │   └── lichess_api.py      # Lichess API integration
│   ├── engine/
│   │   └── downloader.py       # Stockfish binary downloader
│   ├── services/
│   │   └── groq_service.py     # LLM service (multi-provider)
│   ├── storage/
│   │   ├── cache.py            # Analysis cache
│   │   ├── game_history.py     # Game history database
│   │   ├── models.py           # Data model dataclasses
│   │   └── pgn_parser.py       # PGN text parser
│   └── updater/
│       ├── update_checker.py   # GitHub release check
│       └── updater.py          # Platform installer launch
│
├── gui/
│   ├── main_window.py          # Application window and orchestration
│   ├── styles.py               # QSS styling, colors, themes
│   │
│   ├── analysis/               # Analysis view components
│   │   ├── analysis_lines_widget.py
│   │   ├── analysis_panel.py
│   │   ├── analysis_worker.py  # Background analysis thread
│   │   ├── captured.py         # Captured pieces display
│   │   ├── controls.py         # Game navigation controls
│   │   ├── explorer_move_list.py
│   │   ├── live_analysis.py    # Live engine analysis
│   │   ├── move_cell_widget.py # Individual move cell
│   │   ├── move_list_panel.py  # Move list sidebar
│   │   └── think_time_bar.py   # Thinking time visualization
│   │
│   ├── board/                  # Board rendering
│   │   ├── board_widget.py     # Interactive chess board
│   │   ├── eval_bar.py         # Animated evaluation bar
│   │   ├── explorer_board_widget.py
│   │   └── piece_themes.py     # SVG piece theme loader
│   │
│   ├── components/             # Shared UI components
│   │   ├── graph_widget.py     # Evaluation graph
│   │   ├── loading_widget.py   # Loading overlay
│   │   ├── tour_manager.py     # Interactive tour system
│   │   └── tour_overlay.py
│   │
│   ├── dialogs/                # Modal dialogs
│   │   ├── setup_wizard.py     # First-run wizard
│   │   ├── load_game_dialog.py # Unified load dialog
│   │   ├── update_dialog.py    # Update notification
│   │   ├── splash_screen.py    # Startup splash
│   │   ├── engine_error_dialog.py
│   │   ├── llm_error_dialog.py
│   │   └── shortcut_help_dialog.py
│   │
│   ├── metrics/                # Stats dashboard
│   │   ├── charts.py           # Matplotlib chart helpers
│   │   └── workers.py          # Stats computation thread
│   │
│   ├── views/                  # Main view pages
│   │   ├── analysis_view.py    # Analysis page
│   │   ├── explorer_view.py    # Opening Explorer page
│   │   ├── history_view.py     # Game History page
│   │   ├── metrics_view.py     # Stats Dashboard page
│   │   └── settings_view.py    # Settings page
│   │
│   └── utils/
│       └── gui_utils.py        # Shared GUI utilities
│
└── utils/
    ├── config.py               # ConfigManager (JSON)
    ├── logger.py               # Logging setup
    ├── path_utils.py           # Path resolution
    └── resources.py            # Resource manager (sounds, icons)

Async Concurrency

All blocking operations run in background QThread instances to keep the UI responsive.

AnalysisWorker

File: src/gui/analysis/analysis_worker.py

Handles:

Running Stockfish evaluation on every position
Progress reporting via signals (move count, current position)
Emitting the fully analyzed GameAnalysis object on completion

Flow:

AnalysisWorker.run()
    → Analyzer.analyze_game()
        → For each position: engine.analyse() + cache lookup
        → classify_move() for each move
        → calculate_final_accuracy()
        → GameHistoryManager.save_game()
    → emit finished(game_analysis)

ApiWorker

File: src/gui/dialogs/load_game/api_worker.py

Fetches games from Chess.com or Lichess APIs in the background. Emits games_fetched signal with a list of game metadata objects.

Configuration Management

File: src/utils/config.py

ConfigManager uses a singleton pattern (_shared_config) shared across the application. Config is loaded from config.json on startup and saved on every modification.

Key behaviors:

Missing keys are filled from DEFAULT_CONFIG on load
Legacy flat LLM keys (groq_api_key, groq_model) are migrated to the profiles system automatically
Config file is written as pretty-printed JSON

Key Files Reference

File	Lines	Purpose
`main.py`	~20	Application entry point
`constants.py`	~106	App version, API URLs, defaults
`main_window.py`	~720	Window orchestration, sidebar, page switching
`analyzer.py`	~680	Core analysis logic
`engine.py`	~243	Stockfish process management
`move_classifier.py`	~139	Classification heuristics
`math_utils.py`	~132	Win probability, accuracy formulas
`game_history.py`	~224	SQLite persistence
`config.py`	~180	Configuration management
`board_widget.py`	~355	Interactive board rendering
`explorer_view.py`	~1148	Opening Explorer
`setup_wizard.py`	~477	First-run wizard
`piece_themes.py`	~592	SVG theme loading and processing
`groq_service.py`	~357	LLM service

Assets

Located in assets/ directory at the project root:

Directory	Contents
`assets/icons/`	Sidebar and toolbar icons (PNG)
`assets/images/`	Classification icons (SVG), logo, time control icons
`assets/pieces/`	Cburnett SVG piece set (12 files)
`assets/openings/`	Lichess ECO TSV files (a.tsv through e.tsv)
`assets/sounds/`	Game sounds (WAV)
`_generator/`	Icon generation script