Logo
Chess Analyzer Pro
ReleasesDocsBlogDownload

Documentation

Getting StartedUsage GuideConfigurationArchitectureFiles & DataHow We Calculate AnalysisChangelogFor DevelopersTroubleshootingAPI ReferenceUI Components

Chess Analyzer Pro

Free offline chess analysis software powered by Stockfish.

Project

  • GitHub Repository
  • Download
  • Documentation
  • Open Source Credits
  • Report Feedback/Bug

Content

  • Blog
  • Documentation
  • Features

Resources

  • Stockfish Engine
  • Beekeeper Studio
  • My Lichess Profile
  • My Chess.com Profile

Developer

  • Portfolio
  • GitHub Profile
  • LinkedIn
  • Contact Me
Released under the MIT License. Open Source Project.
Back to Docs

Architecture & Data Flow

Chess Analyzer Pro follows a Model-View-Controller (MVC) oriented architecture to ensure separation of concerns between the chess logic, the user interface, and the data management.

High-Level Pattern

  1. Model (Backend): Handles the core logic and data state.
    • State: GameAnalysis objects hold moves, evaluation scores, and metadata.
    • Computation: The Analyzer class manages the heavy lifting of communicating with Stockfish.
  2. View (GUI): Displays the data to the user.
    • PyQt6: The entire UI is built using the Qt framework.
    • Components: BoardWidget, AnalysisPanel, MoveListPanel, MetricsView.
  3. Controller (Logic): Orchestrates the application.
    • Signals & Slots: The Qt event system connects UI actions (like clicking "Next Move") to backend functions.

Directory Structure

Chess_analyzer/
├── main.py                 # Application entry point
├── config.json             # User configuration (saved settings)
├── analysis_cache.db       # SQLite database for game history & cache
├── requirements.txt        # Python dependencies
├── build.spec              # PyInstaller configuration
│
├── assets/                 # Static resources
│   ├── icons/              # SVG/PNG icons for classifications
│   ├── images/             # Logo, backgrounds
│   ├── pieces/             # Piece theme directories (cburnett, merida, etc.)
│   └── sounds/             # Audio files for moves, captures, etc.
│
├── src/                    # Source code
│   ├── constants.py        # App-wide constants & paths
│   │
│   ├── backend/            # Core logic, analysis, and data handling
│   │   ├── analysis/       # Engine integration & classification
│   │   │   ├── analyzer.py       # Main analysis engine
│   │   │   ├── engine.py         # Stockfish UCI wrapper
│   │   │   ├── local_book.py     # Local SQLite opening book
│   │   │   ├── math_utils.py     # Win probability, math helpers
│   │   │   ├── move_classifier.py # Separate move classification logic
│   │   │   ├── opening_db.py     # Opening database management
│   │   │   └── polyglot_book.py  # Polyglot .bin book support
│   │   │
│   │   ├── api/            # Chess platform API integrations
│   │   │   ├── base_api.py       # Shared API utilities
│   │   │   ├── chess_com_api.py  # Chess.com API integration
│   │   │   └── lichess_api.py    # Lichess API integration
│   │   │
│   │   ├── services/       # External service integrations
│   │   │   └── groq_service.py   # LLM provider (Groq, LM Studio, etc.)
│   │   │
│   │   ├── storage/        # Data persistence
│   │   │   ├── cache.py         # Position analysis caching
│   │   │   ├── game_history.py  # SQLite game persistence
│   │   │   ├── models.py        # Data structures
│   │   │   └── pgn_parser.py    # PGN file parsing
│   │   │
│   │   └── updater/        # Auto-update mechanism
│   │       ├── update_checker.py # Version check against GitHub
│   │       └── updater.py        # Platform-native update install
│   │
│   ├── gui/                # User Interface components (PyQt6)
│   │   ├── main_window.py       # Root application window
│   │   ├── styles.py            # QSS theming & color constants
│   │   │
│   │   ├── analysis/       # Analysis-specific widgets
│   │   │   ├── analysis_lines_widget.py # Multi-PV line display
│   │   │   ├── analysis_panel.py       # Main analysis layout
│   │   │   ├── analysis_worker.py      # Background analysis thread
│   │   │   ├── captured.py            # Captured pieces display
│   │   │   ├── controls.py            # Game navigation buttons
│   │   │   ├── explorer_move_list.py  # Explorer move history
│   │   │   ├── live_analysis.py       # Real-time position analysis
│   │   │   ├── move_cell_widget.py    # Single move cell rendering
│   │   │   ├── move_list_panel.py     # Full move list container
│   │   │   └── think_time_bar.py      # Move timing visualization
│   │   │
│   │   ├── board/          # Chessboard components
│   │   │   ├── board_widget.py         # Main board renderer
│   │   │   ├── eval_bar.py            # Evaluation bar widget
│   │   │   ├── explorer_board_widget.py # Explorer board (drag & drop)
│   │   │   └── piece_themes.py        # Piece set management
│   │   │
│   │   ├── components/     # Reusable UI components
│   │   │   ├── game_list_item_widget.py # Single game card
│   │   │   ├── game_list_widget.py     # Paginated game list
│   │   │   ├── graph_widget.py         # Evaluation curve (matplotlib)
│   │   │   ├── loading_widget.py       # Animated loading overlay
│   │   │   ├── masonry_layout.py       # Responsive grid layout
│   │   │   ├── sidebar.py             # Navigation sidebar
│   │   │   ├── skeleton_widget.py     # Skeleton loader placeholder
│   │   │   ├── stat_card.py           # Stats display card
│   │   │   └── stats_layout.py        # Stats grid layout helper
│   │   │
│   │   ├── dialogs/        # Modal dialogs
│   │   │   ├── game_selection_dialog.py # Game picker dialog
│   │   │   ├── load_game_dialog.py     # Unified load dialog
│   │   │   ├── shortcut_help_dialog.py # Keyboard shortcuts reference
│   │   │   ├── splash_screen.py        # Startup splash screen
│   │   │   ├── update_dialog.py        # Update notification dialog
│   │   │   │
│   │   │   └── load_game/  # Load dialog sub-panels
│   │   │       ├── api_worker.py         # Background fetch worker
│   │   │       ├── chesscom_panel.py     # Chess.com tab
│   │   │       ├── drop_zone.py          # File drag & drop zone
│   │   │       ├── game_card.py          # Game metadata card
│   │   │       ├── helpers.py            # Panel shared utilities
│   │   │       ├── inline_game_list.py   # Inline game results list
│   │   │       ├── lichess_panel.py      # Lichess tab
│   │   │       ├── pgn_file_panel.py     # PGN file tab
│   │   │       ├── pgn_text_panel.py     # PGN text tab
│   │   │       └── source_button.py      # Source tab button
│   │   │
│   │   ├── metrics/        # Dashboard charts & workers
│   │   │   ├── charts.py   # Chart generation (donut, line)
│   │   │   └── workers.py  # Background stat calculation
│   │   │
│   │   ├── utils/          # GUI helper utilities
│   │   │   └── gui_utils.py
│   │   │
│   │   └── views/          # Main view pages
│   │       ├── analysis_view.py   # Analysis dashboard
│   │       ├── explorer_view.py   # Opening Explorer view
│   │       ├── history_view.py    # Game history browser
│   │       ├── metrics_view.py    # Stats dashboard
│   │       ├── settings_view.py   # Settings panel
│   │       │
│   │       ├── metrics/     # Stats sub-panels
│   │       │   ├── accuracy_trend_card.py
│   │       │   ├── ai_coach_card.py
│   │       │   ├── base_card.py
│   │       │   ├── color_performance_card.py
│   │       │   ├── ending_distribution_card.py
│   │       │   ├── move_quality_card.py
│   │       │   ├── openings_list_card.py
│   │       │   └── result_distribution_card.py
│   │       │
│   │       └── settings/   # Settings sub-panels
│   │           ├── api_settings.py
│   │           ├── appearance_settings.py
│   │           ├── book_settings.py
│   │           ├── data_settings.py
│   │           ├── engine_settings.py
│   │           ├── helpers.py
│   │           ├── links_settings.py
│   │           └── player_settings.py
│   │
│   └── utils/              # Shared utilities
│       ├── config.py       # Configuration file management
│       ├── logger.py       # Logging setup
│       ├── path_utils.py   # Resource path resolution
│       └── resources.py    # Asset loading helpers
│
├── tests/                  # pytest suite
│   ├── conftest.py
│   ├── test_app_load.py
│   ├── test_game_load.py
│   ├── backend/
│   ├── gui/
│   └── utils/

Key Components

Backend (src/backend/)

ComponentResponsibility
analysis/analyzer.pyThe Brain. Manages the analysis queue, calculates Win Probability Loss (WPL), determines move classifications, computes accuracy using Lichess-style algorithm, and updates the game state.
analysis/engine.pyStockfish Bridge. Wraps the Stockfish process using python-chess. Handles UCI protocol commands (position, go, stop) and parses engine output.
analysis/move_classifier.pyMove Classification. Standalone classification logic evaluating Brilliant, Great, Best, Excellent, Good, Inaccuracy, Mistake, Blunder, Miss against configurable WPL thresholds.
analysis/local_book.pyLocal Opening Book. SQLite-based opening book for detecting known lines from the ECO dataset.
analysis/polyglot_book.pyPolyglot Support. Reader for Polyglot .bin opening book files, configurable in Settings.
analysis/opening_db.pyOpening Database. Management of the built-in opening database (ECO classification, Polyglot indexing).
analysis/math_utils.pyMath Helpers. Win probability conversion (sigmoid), harmonic mean, accuracy decay functions.
api/base_api.pyAPI Utilities. Shared request handling, error logging, and JSON parsing for API classes.
api/chess_com_api.pyChess.com Integration. Fetches games from Chess.com usernames or game URLs.
api/lichess_api.pyLichess Integration. Fetches games from Lichess usernames or game URLs with token auth.
services/groq_service.pyAI Summaries. Provider-agnostic LLM service (Groq, LM Studio, MiniMax, custom endpoints) for generating game summaries and coaching insights.
storage/game_history.pyPersistence. SQLite database manager for saving/loading analyzed games with full metadata and move data.
storage/cache.pyPerformance. Caches engine analysis results by FEN to avoid re-analyzing known positions.
storage/models.pyData Types. Single source of truth for data structures: GameAnalysis, MoveAnalysis, GameMetadata.
storage/pgn_parser.pyData Ingestion. Robust parsing of .pgn files to extract moves, headers, and comments.
updater/update_checker.pyVersion Check. Queries GitHub Releases API once per day to check for new versions.
updater/updater.pyUpdate Installer. Platform-native update logic: Inno Setup (Windows), DMG (macOS), AppImage (Linux).

GUI (src/gui/)

ComponentResponsibility
main_window.pyRoot Container. Initializes the application window, sidebar, page stack, and routes global events. Manages game loading and analysis orchestration.
board/board_widget.pyVisuals. Renders the chess board with customizable themes, pieces, arrows (for best moves), and highlights (last move, check).
board/explorer_board_widget.pyExplorer Board. Variant of the board widget with drag-and-drop piece movement and SAN text input for the Explorer tab.
board/eval_bar.pyEvaluation Bar. Vertical bar showing white/black advantage percentage.
board/piece_themes.pyPiece Sets. Manages loading and applying different piece styles (cburnett, merida, etc.).
analysis/analysis_panel.pyDashboard. The central analysis layout: board, stats, graphs, and move list side-by-side.
analysis/analysis_worker.pyBackground Thread. Runs the full game analysis in a separate thread to keep the UI responsive.
analysis/live_analysis.pyLive Engine. Real-time Stockfish analysis on the current board position with configurable time budget.
analysis/move_list_panel.pyMove List. Scrollable list of moves with classification icons, evaluation badges, and navigation.
analysis/analysis_lines_widget.pyEngine Lines. Shows top Multi-PV lines with evaluation scores and move sequences.
analysis/explorer_move_list.pyExplorer Moves. Move history list specific to the Explorer tab.
analysis/think_time_bar.pyTime Visualization. Displays per-move clock data as horizontal bars.
components/graph_widget.pyVisualization. Uses matplotlib to draw the evaluation curve with hover tooltips and classification markers.
components/sidebar.pyNavigation. Sidebar with buttons for each view, theme toggle, and help.
components/masonry_layout.pyLayout. Custom responsive 2-column masonry layout for the settings and stats views.
dialogs/load_game_dialog.pyUnified Load Dialog. Modal dialog with 4 source tabs (PGN File, PGN Text, Chess.com, Lichess), async game fetching, and inline game selection.
dialogs/update_dialog.pyUpdate Dialog. Notification dialog with formatted changelog and download button.
views/metrics_view.pyStatistics Dashboard. Displays aggregate performance metrics, charts (donut, line), openings analysis, and AI coaching insights. Uses modular card components from views/metrics/.
views/explorer_view.pyOpening Explorer. Standalone exploration view with independent board, book moves panel, and live engine analysis. New in v2.1.0.
views/settings_view.pySettings Panel. UI for configuring engine path, API keys, themes, usernames, book settings, and data management. Uses sub-panels from views/settings/.

Utils (src/utils/)

ComponentResponsibility
config.pyManages config.json for saving user settings (theme, engine path, API keys, board/piece themes, usernames, book paths).
logger.pySets up the application logging (writes to chess_analyzer.log).
path_utils.pyResolves resource paths correctly for both development and PyInstaller builds.
resources.pyHelper functions for loading images, icons, and sounds from the assets directory.

Data Flow Example: Analysis Loop

  1. User Action: User clicks "Analyze Game".
  2. Controller: MainWindow creates an AnalysisWorker thread and starts it.
  3. Backend Processing:
    • AnalysisWorker calls analyzer.analyze_game() with the GameAnalysis object.
    • analyzer iterates through every move in the game.
    • For each position, it checks cache.py for existing analysis.
    • If not cached, it sends the FEN to engine.py.
    • engine.py queries Stockfish and returns multi-PV analysis.
    • move_classifier.py calculates win probability loss and assigns a classification.
    • Results are cached for future use.
  4. UI Update:
    • AnalysisWorker emits progress_update signal with current/total move count.
    • MainWindow updates the progress display.
    • When complete, finished signal triggers UI refresh.
  5. Persistence:
    • game_history.save_game() stores the analyzed game to SQLite.

Data Flow: Stats Dashboard

  1. User Action: User navigates to Stats page.
  2. Background Worker: metrics/workers.py runs in a separate thread to calculate aggregate statistics.
  3. Data Collection: Worker queries game_history for all games matching configured usernames.
  4. Calculation: Aggregates win/loss/draw rates, accuracy trends, opening frequency, termination types, and color performance.
  5. UI Update: Worker emits signals with stats; metrics_view.py renders modular card components.
  6. AI Insights (optional): If Groq API is configured, groq_service generates coaching insights from the stats.

Data Flow: Opening Explorer

  1. User Action: Right-click a move in the main analysis and select "Explore from here" (or open Explorer directly from sidebar).
  2. View Initialization: explorer_view.py opens with an independent board and position loaded.
  3. Book Moves: Queries local_book.py (SQLite) and polyglot_book.py (.bin files) for book suggestions at the current position.
  4. Live Engine: live_analysis.py runs Stockfish on the current position with Multi-PV.
  5. User Exploration: Dragging pieces or typing SAN moves triggers re-analysis of the new position. The Explorer maintains its own move history and classification.

Data Flow: Auto-Update

  1. Startup: main_window.py launches update_checker.py in a background thread.
  2. Version Check: Queries https://api.github.com/repos/imutkarsht/Chess_analyzer/releases/latest, compares with current version from packaging.
  3. Notification: If a newer version is found, update_dialog.py shows a modal with the changelog.
  4. Download: User clicks "Download" which opens the releases page in their browser. The installer is platform-native.

Architecture Diagram