# imutkarsht/chess_analyzer architecture

> Architecture diagram of the GitHub repository imutkarsht/chess_analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imutkarsht/chess_analyzer
- Repository: https://github.com/imutkarsht/chess_analyzer

## Overview

Chess Analyzer Pro is a local-first desktop chess analysis application. The main workflow starts in the desktop app, imports a game from PGN or an online account, analyzes positions with Stockfish, and presents move, tactical, and performance insights. The graph also preserves the documented opening-explorer, history, AI-coach, settings, and import capabilities. Relationships are limited to README statements and SOURCE INDEX references; several unsampled GUI and storage connections are therefore omitted rather than inferred.

Main entry points: [`src/backend/analysis/analyzer.py`](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/analyzer.py) (Game analyzer), [`src/backend/analysis/tactics/game.py`](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/game.py) (Tactical analysis), [`src/backend/analysis/engine.py`](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/engine.py) (Stockfish manager), [`main.py`](https://github.com/imutkarsht/chess_analyzer/blob/master/main.py) (App startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_entry["App startup<br/>[main.py]"]
  node_window["Main window<br/>[window.py]"]
  node_setup["First-run setup<br/>[setup_wizard.py]"]
  node_settings["Engine settings<br/>[engine_settings.py]"]
  node_style["Interface styling<br/>[styles.py]"]
  node_palette["Theme palette<br/>[palette.py]"]
end

subgraph group_ingest["Game import and history"]
  node_importui["Game import UI"]
  node_pgn["PGN parser<br/>[pgn_parser.py]"]
  node_online["Chess APIs<br/>[lichess_api.py]"]
  node_history[("Game history<br/>[games_repo.py]")]
end

subgraph group_analysis["Chess analysis"]
  node_engine["Stockfish manager<br/>[engine.py]"]
  node_download["Engine downloader<br/>[downloader.py]"]
  node_analyzer["Game analyzer<br/>[analyzer.py]"]
  node_math["Score utilities<br/>[math_utils.py]"]
  node_tactics["Tactical analysis<br/>[game.py]"]
  node_boardutils["Board utilities<br/>[board_utils.py]"]
  node_hanging["Hanging pieces<br/>[hanging.py]"]
  node_motifs["Tactical motifs<br/>[motifs.py]"]
  node_see["Exchange evaluation<br/>[see.py]"]
end

subgraph group_insights["Insights and integrations"]
  node_opening["Opening explorer<br/>[explorer_view.py]"]
  node_metrics["Performance dashboard"]
  node_drilldown["Metric drill-down<br/>[drill_down_view.py]"]
  node_coach["AI coach<br/>[groq_service.py]"]
  node_coachworker["Coach worker<br/>[coach_worker.py]"]
  node_feedback["Feedback service"]
end

subgraph group_support["Local runtime support"]
  node_cache[("Analysis cache<br/>[cache.py]")]
  node_models["Game data models<br/>[models.py]"]
  node_config["User configuration<br/>[config.py]"]
  node_pathutils["Local paths<br/>[path_utils.py]"]
  node_logger["Application logging<br/>[logger.py]"]
end

node_user(("Chess player"))

node_user -->|"starts"| node_entry
node_entry -->|"opens"| node_window
node_entry -->|"resolves engine"| node_engine
node_entry -->|"opens when needed"| node_setup
node_user -.->|"imports game"| node_importui
node_importui -.->|"fetches online games"| node_online
node_importui -.->|"loads PGN"| node_pgn
node_pgn -->|"creates models"| node_models
node_user -.->|"opens saved games"| node_history
node_analyzer -->|"uses engine"| node_engine
node_analyzer -->|"reads and writes"| node_cache
node_analyzer -->|"uses game data"| node_models
node_analyzer -->|"uses scoring"| node_math
node_analyzer -->|"uses history"| node_history
node_engine -->|"uses downloader"| node_download
node_tactics -->|"uses scoring"| node_math
node_tactics -->|"uses board helpers"| node_boardutils
node_tactics -->|"uses hanging analysis"| node_hanging
node_tactics -->|"detects motifs"| node_motifs
node_hanging -->|"uses board helpers"| node_boardutils
node_hanging -->|"uses exchange evaluation"| node_see
node_motifs -->|"uses board helpers"| node_boardutils
node_motifs -->|"uses exchange evaluation"| node_see
node_user -.->|"explores openings"| node_opening
node_user -.->|"views performance"| node_metrics
node_user -.->|"explores metrics"| node_drilldown
node_coachworker -->|"requests summaries"| node_coach
node_coachworker -->|"uses cache"| node_cache
node_coachworker -->|"requests insights"| node_tactics
node_user -.->|"submits feedback"| node_feedback
node_setup -.->|"configures settings"| node_config
node_settings -.->|"reads settings"| node_config
node_config -->|"locates data"| node_pathutils
node_engine -->|"reads engine options"| node_config
node_style -->|"uses colors"| node_palette
node_analyzer -->|"logs activity"| node_logger
node_engine -->|"logs activity"| node_logger

click node_entry "https://github.com/imutkarsht/chess_analyzer/blob/master/main.py"
click node_window "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/main_window/window.py"
click node_setup "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/dialogs/setup_wizard.py"
click node_settings "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/views/settings/engine_settings.py"
click node_importui "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/dialogs/load_game/online_fetch_panel.py"
click node_pgn "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/pgn_parser.py"
click node_online "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/api/lichess_api.py"
click node_history "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/games_repo.py"
click node_engine "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/engine.py"
click node_download "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/engine/downloader.py"
click node_analyzer "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/analyzer.py"
click node_math "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/math_utils.py"
click node_tactics "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/game.py"
click node_boardutils "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/board_utils.py"
click node_hanging "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/hanging.py"
click node_motifs "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/motifs.py"
click node_see "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/see.py"
click node_cache "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/cache.py"
click node_models "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/models.py"
click node_config "https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/config.py"
click node_pathutils "https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/path_utils.py"
click node_logger "https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/logger.py"
click node_opening "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/views/explorer_view.py"
click node_metrics "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/metrics_aggregator.py"
click node_drilldown "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/metrics/drill_down_view.py"
click node_coach "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/services/groq_service.py"
click node_coachworker "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/analysis/coach_worker.py"
click node_feedback "https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/services/feedback_service.py"
click node_style "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/styles.py"
click node_palette "https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/theme/palette.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_window,node_setup,node_settings,node_style,node_palette toneBlue
class node_importui,node_pgn,node_online,node_history toneAmber
class node_engine,node_download,node_analyzer,node_math,node_tactics,node_boardutils,node_hanging,node_motifs,node_see toneMint
class node_opening,node_metrics,node_drilldown,node_coach,node_coachworker,node_feedback toneRose
class node_cache,node_models,node_config,node_pathutils,node_logger,node_user toneIndigo
```

## Components

### Desktop app

- [App startup](https://github.com/imutkarsht/chess_analyzer/blob/master/main.py): `main.py`
- [Main window](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/main_window/window.py): `src/gui/main_window/window.py`
- [First-run setup](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/dialogs/setup_wizard.py): `src/gui/dialogs/setup_wizard.py`
- [Engine settings](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/views/settings/engine_settings.py): `src/gui/views/settings/engine_settings.py`
- [Interface styling](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/styles.py): `src/gui/styles.py`
- [Theme palette](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/theme/palette.py): `src/gui/theme/palette.py`

### Game import and history

- [Game import UI](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/dialogs/load_game/online_fetch_panel.py): `src/gui/dialogs/load_game/online_fetch_panel.py`
- [PGN parser](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/pgn_parser.py): `src/backend/storage/pgn_parser.py`
- [Chess APIs](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/api/lichess_api.py): `src/backend/api/lichess_api.py`
- [Game history](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/games_repo.py): `src/backend/storage/games_repo.py`

### Chess analysis

- [Stockfish manager](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/engine.py): `src/backend/analysis/engine.py`
- [Engine downloader](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/engine/downloader.py): `src/backend/engine/downloader.py`
- [Game analyzer](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/analyzer.py): `src/backend/analysis/analyzer.py`
- [Score utilities](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/math_utils.py): `src/backend/analysis/math_utils.py`
- [Tactical analysis](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/game.py): `src/backend/analysis/tactics/game.py`
- [Board utilities](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/board_utils.py): `src/backend/analysis/tactics/board_utils.py`
- [Hanging pieces](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/hanging.py): `src/backend/analysis/tactics/hanging.py`
- [Tactical motifs](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/motifs.py): `src/backend/analysis/tactics/motifs.py`
- [Exchange evaluation](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/tactics/see.py): `src/backend/analysis/tactics/see.py`

### Insights and integrations

- [Opening explorer](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/views/explorer_view.py): `src/gui/views/explorer_view.py`
- [Performance dashboard](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/analysis/metrics_aggregator.py): `src/backend/analysis/metrics_aggregator.py`
- [Metric drill-down](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/metrics/drill_down_view.py): `src/gui/metrics/drill_down_view.py`
- [AI coach](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/services/groq_service.py): `src/backend/services/groq_service.py`
- [Coach worker](https://github.com/imutkarsht/chess_analyzer/blob/master/src/gui/analysis/coach_worker.py): `src/gui/analysis/coach_worker.py`
- [Feedback service](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/services/feedback_service.py): `src/backend/services/feedback_service.py`

### Local runtime support

- [Analysis cache](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/cache.py): `src/backend/storage/cache.py`
- [Game data models](https://github.com/imutkarsht/chess_analyzer/blob/master/src/backend/storage/models.py): `src/backend/storage/models.py`
- [User configuration](https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/config.py): `src/utils/config.py`
- [Local paths](https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/path_utils.py): `src/utils/path_utils.py`
- [Application logging](https://github.com/imutkarsht/chess_analyzer/blob/master/src/utils/logger.py): `src/utils/logger.py`

### Other components

- **Chess player**

## Connections

- Chess player → App startup: starts (evidence: `main.py`)
- App startup → Main window: opens (evidence: `main.py`)
- App startup → Stockfish manager: resolves engine (evidence: `main.py`)
- App startup → First-run setup: opens when needed (evidence: `main.py`)
- Chess player → Game import UI: imports game (evidence: `README.md`)
- Game import UI → Chess APIs: fetches online games (evidence: `README.md`)
- Game import UI → PGN parser: loads PGN (evidence: `README.md`)
- PGN parser → Game data models: creates models (evidence: `src/backend/storage/pgn_parser.py`)
- Chess player → Game history: opens saved games (evidence: `README.md`)
- Game analyzer → Stockfish manager: uses engine (evidence: `src/backend/analysis/analyzer.py`)
- Game analyzer → Analysis cache: reads and writes (evidence: `src/backend/analysis/analyzer.py`)
- Game analyzer → Game data models: uses game data (evidence: `src/backend/analysis/analyzer.py`)
- Game analyzer → Score utilities: uses scoring (evidence: `src/backend/analysis/analyzer.py`)
- Game analyzer → Game history: uses history (evidence: `src/backend/analysis/analyzer.py`)
- Stockfish manager → Engine downloader: uses downloader (evidence: `src/backend/analysis/engine.py`)
- Tactical analysis → Score utilities: uses scoring (evidence: `src/backend/analysis/tactics/game.py`)
- Tactical analysis → Board utilities: uses board helpers (evidence: `src/backend/analysis/tactics/game.py`)
- Tactical analysis → Hanging pieces: uses hanging analysis (evidence: `src/backend/analysis/tactics/game.py`)
- Tactical analysis → Tactical motifs: detects motifs (evidence: `src/backend/analysis/tactics/game.py`)
- Hanging pieces → Board utilities: uses board helpers (evidence: `src/backend/analysis/tactics/hanging.py`)
- Hanging pieces → Exchange evaluation: uses exchange evaluation (evidence: `src/backend/analysis/tactics/hanging.py`)
- Tactical motifs → Board utilities: uses board helpers (evidence: `src/backend/analysis/tactics/motifs.py`)
- Tactical motifs → Exchange evaluation: uses exchange evaluation (evidence: `src/backend/analysis/tactics/motifs.py`)
- Chess player → Opening explorer: explores openings (evidence: `README.md`)
- Chess player → Performance dashboard: views performance (evidence: `README.md`)
- Chess player → Metric drill-down: explores metrics (evidence: `README.md`)
- Coach worker → AI coach: requests summaries (evidence: `src/gui/analysis/coach_worker.py`)
- Coach worker → Analysis cache: uses cache (evidence: `src/gui/analysis/coach_worker.py`)
- Coach worker → Tactical analysis: requests insights (evidence: `src/gui/analysis/coach_worker.py`)
- Chess player → Feedback service: submits feedback (evidence: `README.md`)
- First-run setup → User configuration: configures settings
- Engine settings → User configuration: reads settings (evidence: `src/gui/views/settings/engine_settings.py`)
- User configuration → Local paths: locates data (evidence: `src/utils/config.py`)
- Stockfish manager → User configuration: reads engine options (evidence: `src/backend/analysis/engine.py`)
- Interface styling → Theme palette: uses colors (evidence: `src/gui/styles.py`)
- Game analyzer → Application logging: logs activity (evidence: `src/backend/analysis/analyzer.py`)
- Stockfish manager → Application logging: logs activity (evidence: `src/backend/analysis/engine.py`)
