# goldmangrey/chess.com-cheat architecture

> Architecture diagram of the GitHub repository goldmangrey/chess.com-cheat, 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/goldmangrey/chess.com-cheat
- Repository: https://github.com/goldmangrey/chess.com-cheat

## Overview

Chess Practice Overlay is a Chrome extension that turns Chess.com board state into local Stockfish hints and displays them over the board. Its main workflow detects the game and board, parses pieces into position snapshots, validates reachable moves with chess.js, requests engine analysis through the extension’s background/offscreen path, then renders the best move as an SVG overlay. The popup controls hint visibility and engine depth. README documents the overall pipeline; sampled source confirms key construction and messaging relationships. The content excerpt contains a commented-out mode gate, so the graph does not imply that gate currently blocks unsupported modes.

Main entry points: [`src/content/index.ts`](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/content/index.ts) (Content session), [`src/engine/analysis-controller.ts`](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/engine/analysis-controller.ts) (Analysis controller), [`src/overlay/board-overlay.ts`](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/board-overlay.ts) (Board overlay), [`src/popup/App.tsx`](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/popup/App.tsx) (Settings popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Chess.com Position Capture"]
  node_boarddetect["Board detector<br/>[board-detector.ts]"]
  node_modedetect["Game mode<br/>[game-mode.ts]"]
  node_pieceparse["Piece parser<br/>[piece-parser.ts]"]
  node_fenbuild["FEN builder<br/>[fen-builder.ts]"]
  node_positionobserve["Position observer"]
  node_orientation["Board orientation<br/>[orientation.ts]"]
  node_playercolor["Player color<br/>[player-color.ts]"]
end

subgraph group_analysis["Chess Analysis"]
  node_chessstate["Legal move state<br/>[chess-state.ts]"]
  node_controller["Analysis controller"]
  node_client["Engine client"]
  node_stockfish["Stockfish worker"]
end

subgraph group_presentation["Overlay Presentation"]
  node_overlay["Board overlay<br/>[board-overlay.ts]"]
  node_arrows["Arrow rendering<br/>[arrows.ts]"]
  node_coordinates["Board coordinates<br/>[coordinates.ts]"]
end

subgraph group_extension["Extension Runtime"]
  node_content["Content session<br/>[index.ts]"]
  node_background["Service worker<br/>[service-worker.ts]"]
  node_offscreen["Offscreen engine host<br/>[index.ts]"]
  node_popup["Settings popup<br/>[App.tsx]"]
end

node_chesscom(("Chess.com board"))
node_user(("Extension user"))
node_storage[("Chrome local storage")]

node_chesscom -->|"provides DOM"| node_boarddetect
node_content -->|"detects board"| node_boarddetect
node_content -->|"detects mode"| node_modedetect
node_content -->|"checks orientation"| node_orientation
node_content -->|"detects color"| node_playercolor
node_positionobserve -.->|"parses pieces"| node_pieceparse
node_positionobserve -->|"builds snapshots"| node_fenbuild
node_fenbuild -->|"parses pieces"| node_pieceparse
node_content -->|"tracks position"| node_positionobserve
node_content -->|"creates snapshots"| node_fenbuild
node_content -->|"validates moves"| node_chessstate
node_content -->|"starts analysis"| node_controller
node_controller -->|"requests analysis"| node_client
node_controller -->|"draws result"| node_overlay
node_client -->|"sends requests"| node_background
node_background -->|"forwards engine work"| node_offscreen
node_offscreen -->|"runs worker"| node_stockfish
node_overlay -->|"renders hints"| node_arrows
node_arrows -->|"maps squares"| node_coordinates
node_overlay -->|"overlays board"| node_chesscom
node_user -->|"changes settings"| node_popup
node_popup -->|"reads and writes"| node_storage
node_popup -->|"sends settings"| node_content
node_content -->|"loads settings"| node_storage

click node_boarddetect "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/board-detector.ts"
click node_modedetect "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/game-mode.ts"
click node_pieceparse "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/piece-parser.ts"
click node_fenbuild "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/fen-builder.ts"
click node_positionobserve "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/position-observer.ts"
click node_orientation "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/orientation.ts"
click node_playercolor "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/player-color.ts"
click node_chessstate "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/shared/chess-state.ts"
click node_content "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/content/index.ts"
click node_controller "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/engine/analysis-controller.ts"
click node_client "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/engine/stockfish-client.ts"
click node_background "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/background/service-worker.ts"
click node_offscreen "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/offscreen/index.ts"
click node_stockfish "https://github.com/goldmangrey/chess.com-cheat/blob/main/public/engine/stockfish-18-lite-single.js"
click node_overlay "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/board-overlay.ts"
click node_arrows "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/arrows.ts"
click node_coordinates "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/coordinates.ts"
click node_popup "https://github.com/goldmangrey/chess.com-cheat/blob/main/src/popup/App.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_boarddetect,node_modedetect,node_pieceparse,node_fenbuild,node_positionobserve,node_orientation,node_playercolor,node_user toneBlue
class node_chessstate,node_controller,node_client,node_stockfish,node_storage toneAmber
class node_overlay,node_arrows,node_coordinates toneMint
class node_content,node_background,node_offscreen,node_popup toneRose
class node_chesscom toneIndigo
```

## Components

### Chess.com Position Capture

- [Board detector](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/board-detector.ts): `src/platform/chesscom/board-detector.ts`
- [Game mode](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/game-mode.ts): `src/platform/chesscom/game-mode.ts`
- [Piece parser](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/piece-parser.ts): `src/platform/chesscom/piece-parser.ts`
- [FEN builder](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/fen-builder.ts): `src/platform/chesscom/fen-builder.ts`
- [Position observer](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/position-observer.ts): `src/platform/chesscom/position-observer.ts`
- [Board orientation](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/orientation.ts): `src/platform/chesscom/orientation.ts`
- [Player color](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/platform/chesscom/player-color.ts): `src/platform/chesscom/player-color.ts`

### Chess Analysis

- [Legal move state](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/shared/chess-state.ts): `src/shared/chess-state.ts`
- [Analysis controller](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/engine/analysis-controller.ts): `src/engine/analysis-controller.ts`
- [Engine client](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/engine/stockfish-client.ts): `src/engine/stockfish-client.ts`
- [Stockfish worker](https://github.com/goldmangrey/chess.com-cheat/blob/main/public/engine/stockfish-18-lite-single.js): `public/engine/stockfish-18-lite-single.js`

### Overlay Presentation

- [Board overlay](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/board-overlay.ts): `src/overlay/board-overlay.ts`
- [Arrow rendering](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/arrows.ts): `src/overlay/arrows.ts`
- [Board coordinates](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/overlay/coordinates.ts): `src/overlay/coordinates.ts`

### Extension Runtime

- [Content session](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/content/index.ts): `src/content/index.ts`
- [Service worker](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/background/service-worker.ts): `src/background/service-worker.ts`
- [Offscreen engine host](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/offscreen/index.ts): `src/offscreen/index.ts`
- [Settings popup](https://github.com/goldmangrey/chess.com-cheat/blob/main/src/popup/App.tsx): `src/popup/App.tsx`

### Other components

- **Chess.com board**
- **Extension user**
- **Chrome local storage**

## Connections

- Chess.com board → Board detector: provides DOM (evidence: `README.md`)
- Content session → Board detector: detects board (evidence: `src/content/index.ts`)
- Content session → Game mode: detects mode (evidence: `src/content/index.ts`)
- Content session → Board orientation: checks orientation (evidence: `src/content/index.ts`)
- Content session → Player color: detects color (evidence: `src/content/index.ts`)
- Position observer → Piece parser: parses pieces
- Position observer → FEN builder: builds snapshots (evidence: `src/platform/chesscom/position-observer.ts`)
- FEN builder → Piece parser: parses pieces (evidence: `src/platform/chesscom/fen-builder.ts`)
- Content session → Position observer: tracks position (evidence: `README.md`)
- Content session → FEN builder: creates snapshots (evidence: `src/content/index.ts`)
- Content session → Legal move state: validates moves (evidence: `src/content/index.ts`)
- Content session → Analysis controller: starts analysis (evidence: `src/content/index.ts`)
- Analysis controller → Engine client: requests analysis (evidence: `src/engine/analysis-controller.ts`)
- Analysis controller → Board overlay: draws result (evidence: `src/engine/analysis-controller.ts`)
- Engine client → Service worker: sends requests (evidence: `src/engine/stockfish-client.ts`)
- Service worker → Offscreen engine host: forwards engine work (evidence: `README.md`)
- Offscreen engine host → Stockfish worker: runs worker (evidence: `src/offscreen/index.ts`)
- Board overlay → Arrow rendering: renders hints (evidence: `src/overlay/board-overlay.ts`)
- Arrow rendering → Board coordinates: maps squares (evidence: `src/overlay/arrows.ts`)
- Board overlay → Chess.com board: overlays board (evidence: `README.md`)
- Extension user → Settings popup: changes settings (evidence: `src/popup/App.tsx`)
- Settings popup → Chrome local storage: reads and writes (evidence: `src/popup/App.tsx`)
- Settings popup → Content session: sends settings (evidence: `src/popup/App.tsx`)
- Content session → Chrome local storage: loads settings (evidence: `src/content/index.ts`)
