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 (Visual Board), AnalysisPanel (Stats/Graphs), MoveListPanel, MetricsWidget (Dashboard).
3. Controller (Logic): Orchestrates the application.
   • Signals & Slots: The robust event system in Qt connects UI actions (like clicking "Next Move") to backend functions (like "Load Board State").

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
│   ├── backend/            # Core logic, analysis, and data handling
│   │   ├── analyzer.py     # Main analysis engine & move classification
│   │   ├── base_api.py     # Shared API utilities
│   │   ├── book.py         # Opening book lookups
│   │   ├── cache.py        # Position analysis caching
│   │   ├── chess_com_api.py # Chess.com API integration
│   │   ├── engine.py       # Stockfish UCI wrapper
│   │   ├── game_history.py # SQLite game persistence
│   │   ├── gemini_service.py # Google Gemini AI integration
│   │   ├── lichess_api.py  # Lichess API integration
│   │   ├── models.py       # Data structures (GameAnalysis, MoveAnalysis)
│   │   └── pgn_parser.py   # PGN file parsing
│   │
│   ├── gui/                # User Interface components (PyQt6)
│   │   ├── main_window.py  # Root application window
│   │   ├── analysis_view.py # Analysis dashboard layout
│   │   ├── analysis_worker.py # Background analysis thread
│   │   ├── graph_widget.py # Evaluation curve visualization
│   │   ├── game_list.py    # Game selection dialogs
│   │   ├── sidebar.py      # Navigation sidebar
│   │   ├── styles.py       # QSS theming & color constants
│   │   ├── gui_utils.py    # Shared UI helper functions
│   │   ├── live_analysis.py # Real-time position analysis
│   │   ├── loading_widget.py # Loading overlay animations
│   │   ├── metrics_widget.py # Stats dashboard with charts
│   │   │
│   │   ├── analysis/       # Analysis-specific widgets
│   │   │   ├── captured.py # Captured pieces display
│   │   │   └── controls.py # Game navigation buttons
│   │   │
│   │   ├── board/          # Chessboard components
│   │   │   ├── board_widget.py # Main board renderer
│   │   │   ├── eval_bar.py # Evaluation bar widget
│   │   │   └── piece_themes.py # Piece set management
│   │   │
│   │   ├── components/     # Reusable UI components
│   │   │   └── stat_card.py # Stat display card widget
│   │   │
│   │   ├── dialogs/        # Modal dialogs
│   │   │   ├── game_selection_dialog.py # Game picker dialog
│   │   │   └── splash_screen.py # Startup splash screen
│   │   │
│   │   ├── metrics/        # Dashboard charts & workers
│   │   │   ├── charts.py   # Chart generation (donut, line)
│   │   │   └── workers.py  # Background stat calculation
│   │   │
│   │   └── views/          # Main view pages
│   │       ├── history_view.py # Game history browser
│   │       └── settings_view.py # Settings panel
│   │
│   └── utils/              # Helper utilities
│       ├── config.py       # Configuration file management
│       ├── logger.py       # Logging setup
│       ├── path_utils.py   # Resource path resolution
│       └── resources.py    # Asset loading helpers
│
├── tests/                  # pytest suite

Key Components

Backend (src/backend/)

GUI (src/gui/)

Utils (src/utils/)

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.
   • Analyzer calculates win probability, move accuracy, and classifies the move.
   • 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:
   • GameHistoryManager.save_game() stores the analyzed game to SQLite.

Data Flow: Stats Dashboard

1. User Action: User navigates to Stats page.
2. Background Worker: StatsWorker runs in a separate thread to calculate aggregate statistics.
3. Data Collection: Worker queries GameHistoryManager 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; MetricsWidget displays charts and metrics.
6. AI Insights (optional): If Gemini API is configured, generates coaching insights from the stats.