# lutzwolfer/chess.com-bot architecture

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

- Interactive diagram: https://gitdiagram.com/lutzwolfer/chess.com-bot
- Repository: https://github.com/lutzwolfer/chess.com-bot

## Overview

The documented product is a desktop chess.com assistant: the user detects a visible board, starts a game, and receives Stockfish move suggestions or can enable automatic mouse moves. The primary runtime is `python -m bot`; the README also describes board detection, opponent-move observation, and optional move execution. The sampled manager excerpt establishes the main orchestration and UI behavior. Some internal calls are supported by the SOURCE INDEX reference list rather than shown call sites; unsampled subsystems and integrations are not expanded beyond documented behavior.

Main entry points: [`bot/Manager.py`](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/Manager.py) (Game manager), [`bot/MouseControl.py`](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/MouseControl.py) (Mouse control), [`bot/StockfishManager.py`](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/StockfishManager.py) (Move analysis), [`bot/ImageDetection.py`](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/ImageDetection.py) (Board vision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_gui["Desktop GUI<br/>[Manager.py]"]
  node_mainui["Main window UI<br/>[main.ui]"]
end

subgraph group_game["Game coordination"]
  node_entry["Module entry<br/>[__main__.py]"]
  node_manager["Game manager<br/>[Manager.py]"]
  node_mousecontrol["Mouse control<br/>[MouseControl.py]"]
end

subgraph group_vision["Board perception"]
  node_image["Board vision<br/>[ImageDetection.py]"]
end

subgraph group_chess["Chess reasoning"]
  node_board["Chess position<br/>[ChessBoard.py]"]
  node_engine["Move analysis"]
end

subgraph group_support["Runtime support"]
  node_config["Engine configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("Player"))
node_display["Chess.com board"]
node_uci["Stockfish engine"]
node_mouse["Mouse input"]

node_user -->|"starts bot"| node_gui
node_entry -->|"launches UI"| node_manager
node_gui -->|"loads layout"| node_mainui
node_gui -->|"starts worker"| node_manager
node_manager -->|"detects board"| node_image
node_manager -->|"observes moves"| node_image
node_manager -->|"updates position"| node_board
node_manager -->|"requests best move"| node_engine
node_manager -->|"executes move"| node_mousecontrol
node_manager -->|"captures screen"| node_display
node_mousecontrol -.->|"clicks squares"| node_display
node_engine -->|"analyzes position"| node_uci
node_manager -.->|"loads settings"| node_config
node_manager -.->|"records events"| node_logger
node_user -->|"plays game"| node_display

click node_entry "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/__main__.py"
click node_manager "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/Manager.py"
click node_gui "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/Manager.py"
click node_mainui "https://github.com/lutzwolfer/chess.com-bot/blob/master/gui/main.ui"
click node_image "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/ImageDetection.py"
click node_board "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/ChessBoard.py"
click node_engine "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/StockfishManager.py"
click node_mousecontrol "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/MouseControl.py"
click node_config "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/config.py"
click node_logger "https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/logger.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_gui,node_mainui toneBlue
class node_entry,node_manager,node_mousecontrol toneAmber
class node_image toneMint
class node_board,node_engine toneRose
class node_config,node_logger,node_user,node_display,node_uci,node_mouse toneIndigo
```

## Components

### Desktop interface

- [Desktop GUI](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/Manager.py): `bot/Manager.py`
- [Main window UI](https://github.com/lutzwolfer/chess.com-bot/blob/master/gui/main.ui): `gui/main.ui`

### Game coordination

- [Module entry](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/__main__.py): `bot/__main__.py`
- [Game manager](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/Manager.py): `bot/Manager.py`
- [Mouse control](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/MouseControl.py): `bot/MouseControl.py`

### Board perception

- [Board vision](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/ImageDetection.py): `bot/ImageDetection.py`

### Chess reasoning

- [Chess position](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/ChessBoard.py): `bot/ChessBoard.py`
- [Move analysis](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/StockfishManager.py): `bot/StockfishManager.py`

### Runtime support

- [Engine configuration](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/config.py): `bot/config.py`
- [Logging](https://github.com/lutzwolfer/chess.com-bot/blob/master/bot/logger.py): `bot/logger.py`

### Other components

- **Player**
- **Chess.com board**
- **Stockfish engine**
- **Mouse input**

## Connections

- Player → Desktop GUI: starts bot (evidence: `README.md`)
- Module entry → Game manager: launches UI (evidence: `bot/__main__.py`)
- Desktop GUI → Main window UI: loads layout (evidence: `bot/Manager.py`)
- Desktop GUI → Game manager: starts worker (evidence: `bot/Manager.py`)
- Game manager → Board vision: detects board (evidence: `bot/Manager.py`)
- Game manager → Board vision: observes moves (evidence: `bot/Manager.py`)
- Game manager → Chess position: updates position (evidence: `bot/Manager.py`)
- Game manager → Move analysis: requests best move (evidence: `bot/Manager.py`)
- Game manager → Mouse control: executes move (evidence: `bot/Manager.py`)
- Game manager → Chess.com board: captures screen (evidence: `bot/Manager.py`)
- Mouse control → Chess.com board: clicks squares
- Move analysis → Stockfish engine: analyzes position (evidence: `bot/StockfishManager.py`)
- Game manager → Engine configuration: loads settings (evidence: `bot/Manager.py`)
- Game manager → Logging: records events (evidence: `bot/Manager.py`)
- Player → Chess.com board: plays game (evidence: `README.md`)
