# bariskisir/chessbot architecture

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

- Interactive diagram: https://gitdiagram.com/bariskisir/chessbot
- Repository: https://github.com/bariskisir/chessbot

## Overview

ChessBot is a Chrome extension for observing local Stockfish analysis on Chess.com games. The main workflow detects the board and player turn, requests analysis, presents evaluation and candidate moves, and optionally plays a move; automation can also start a new match or rematch after game over. Settings persist across sessions, and mistake mode performs extra searches to choose a weaker move within the configured evaluation floor. The graph follows wiring shown in sampled source; README capabilities without sampled implementation are included only where the tree supports a path.

Main entry points: [`src/controller.ts`](https://github.com/bariskisir/chessbot/blob/master/src/controller.ts) (Session controller), [`src/engine-client.ts`](https://github.com/bariskisir/chessbot/blob/master/src/engine-client.ts) (Engine client), [`src/engine.ts`](https://github.com/bariskisir/chessbot/blob/master/src/engine.ts) (Search queue and worker), [`src/app.tsx`](https://github.com/bariskisir/chessbot/blob/master/src/app.tsx) (Control panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Panel and Settings"]
  node_panel["Control panel<br/>[app.tsx]"]
  node_storage["Settings storage<br/>[storage.ts]"]
end

subgraph group_game["Board and Automation"]
  node_controller["Session controller<br/>[controller.ts]"]
  node_board["Board detection and moves<br/>[board.ts]"]
  node_gameactions["Match actions<br/>[automation.ts]"]
  node_overlay["Extension overlay mount<br/>[mount.tsx]"]
end

subgraph group_analysis["Analysis and Selection"]
  node_selection["Move selection<br/>[move-selection.ts]"]
  node_mistakes["Evaluation and mistakes<br/>[mistake-mode.ts]"]
  node_protocol["Settings and analysis protocol<br/>[shared.ts]"]
end

subgraph group_engine["Local Engine"]
  node_transport["Engine client<br/>[engine-client.ts]"]
  node_dispatcher["Analysis dispatcher<br/>[background.ts]"]
  node_engine["Search queue and worker<br/>[engine.ts]"]
end

node_player(("Chess.com player"))
node_page["Chess.com game page"]
node_preferences[("Extension local storage")]
node_stockfish["Local Stockfish WASM"]

node_player -->|"uses"| node_page
node_page -->|"loads content"| node_overlay
node_overlay -->|"mounts"| node_panel
node_panel -->|"starts and configures"| node_controller
node_controller -->|"loads and saves"| node_storage
node_storage -->|"reads and writes"| node_preferences
node_controller -->|"reads and plays"| node_board
node_controller -->|"finds match actions"| node_gameactions
node_controller -->|"requests searches"| node_transport
node_controller -->|"evaluates and finds mistakes"| node_mistakes
node_controller -->|"chooses move"| node_selection
node_controller -->|"updates state"| node_panel
node_board -->|"reads and dispatches moves"| node_page
node_gameactions -->|"finds and clicks controls"| node_page
node_transport -->|"sends requests"| node_dispatcher
node_dispatcher -->|"routes requests"| node_engine
node_engine -->|"runs UCI searches"| node_stockfish
node_engine -->|"returns results"| node_transport
node_mistakes -->|"requests searches"| node_transport
node_transport -->|"uses message types"| node_protocol
node_engine -->|"parses and validates"| node_protocol

click node_panel "https://github.com/bariskisir/chessbot/blob/master/src/app.tsx"
click node_controller "https://github.com/bariskisir/chessbot/blob/master/src/controller.ts"
click node_storage "https://github.com/bariskisir/chessbot/blob/master/src/storage.ts"
click node_board "https://github.com/bariskisir/chessbot/blob/master/src/board.ts"
click node_gameactions "https://github.com/bariskisir/chessbot/blob/master/src/automation.ts"
click node_selection "https://github.com/bariskisir/chessbot/blob/master/src/move-selection.ts"
click node_mistakes "https://github.com/bariskisir/chessbot/blob/master/src/mistake-mode.ts"
click node_transport "https://github.com/bariskisir/chessbot/blob/master/src/engine-client.ts"
click node_dispatcher "https://github.com/bariskisir/chessbot/blob/master/src/background.ts"
click node_engine "https://github.com/bariskisir/chessbot/blob/master/src/engine.ts"
click node_protocol "https://github.com/bariskisir/chessbot/blob/master/src/shared.ts"
click node_overlay "https://github.com/bariskisir/chessbot/blob/master/src/mount.tsx"

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_panel,node_storage toneBlue
class node_controller,node_board,node_gameactions,node_overlay,node_preferences toneAmber
class node_selection,node_mistakes,node_protocol toneMint
class node_transport,node_dispatcher,node_engine toneRose
class node_player,node_page,node_stockfish toneIndigo
```

## Components

### Panel and Settings

- [Control panel](https://github.com/bariskisir/chessbot/blob/master/src/app.tsx): `src/app.tsx`
- [Settings storage](https://github.com/bariskisir/chessbot/blob/master/src/storage.ts): `src/storage.ts`

### Board and Automation

- [Session controller](https://github.com/bariskisir/chessbot/blob/master/src/controller.ts): `src/controller.ts`
- [Board detection and moves](https://github.com/bariskisir/chessbot/blob/master/src/board.ts): `src/board.ts`
- [Match actions](https://github.com/bariskisir/chessbot/blob/master/src/automation.ts): `src/automation.ts`
- [Extension overlay mount](https://github.com/bariskisir/chessbot/blob/master/src/mount.tsx): `src/mount.tsx`

### Analysis and Selection

- [Move selection](https://github.com/bariskisir/chessbot/blob/master/src/move-selection.ts): `src/move-selection.ts`
- [Evaluation and mistakes](https://github.com/bariskisir/chessbot/blob/master/src/mistake-mode.ts): `src/mistake-mode.ts`
- [Settings and analysis protocol](https://github.com/bariskisir/chessbot/blob/master/src/shared.ts): `src/shared.ts`

### Local Engine

- [Engine client](https://github.com/bariskisir/chessbot/blob/master/src/engine-client.ts): `src/engine-client.ts`
- [Analysis dispatcher](https://github.com/bariskisir/chessbot/blob/master/src/background.ts): `src/background.ts`
- [Search queue and worker](https://github.com/bariskisir/chessbot/blob/master/src/engine.ts): `src/engine.ts`

### Other components

- **Chess.com player**
- **Chess.com game page**
- **Extension local storage**
- **Local Stockfish WASM**

## Connections

- Chess.com player → Chess.com game page: uses
- Chess.com game page → Extension overlay mount: loads content
- Extension overlay mount → Control panel: mounts
- Control panel → Session controller: starts and configures
- Session controller → Settings storage: loads and saves
- Settings storage → Extension local storage: reads and writes
- Session controller → Board detection and moves: reads and plays
- Session controller → Match actions: finds match actions
- Session controller → Engine client: requests searches
- Session controller → Evaluation and mistakes: evaluates and finds mistakes
- Session controller → Move selection: chooses move
- Session controller → Control panel: updates state
- Board detection and moves → Chess.com game page: reads and dispatches moves
- Match actions → Chess.com game page: finds and clicks controls
- Engine client → Analysis dispatcher: sends requests
- Analysis dispatcher → Search queue and worker: routes requests
- Search queue and worker → Local Stockfish WASM: runs UCI searches
- Search queue and worker → Engine client: returns results
- Evaluation and mistakes → Engine client: requests searches
- Engine client → Settings and analysis protocol: uses message types
- Search queue and worker → Settings and analysis protocol: parses and validates