# colochampre/chess-sweeper architecture

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

- Interactive diagram: https://gitdiagram.com/colochampre/chess-sweeper
- Repository: https://github.com/colochampre/chess-sweeper
- Video tour (about a minute): https://gitdiagram.com/colochampre/chess-sweeper/video

## Overview

Chess Minesweeper combines chess legality with hidden mines, cascading reveals and chain explosions. Players choose local, AI or online play; the engine owns authoritative game and room rules, while the client renders event sequences and the server/Worker carry online play. The README documents matchmaking, room codes, clocks, rematches, private flags and synthesized audio. Paths and arrows follow the tree, excerpts and explicit README contracts; unsampled subsystems are included only where documented, with uncertain wiring omitted.

Main entry points: [`packages/client/src/store.ts`](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/store.ts) (Client game state), [`packages/engine/src/game.ts`](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/game.ts) (Game orchestration), [`packages/worker/src/index.ts`](https://github.com/colochampre/chess-sweeper/blob/main/packages/worker/src/index.ts) (Cloudflare Worker), [`packages/client/src/online.ts`](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/online.ts) (Online transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Player experience"]
  node_menu["Modes and setup<br/>[Menu.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_clientstate["Client game state<br/>[store.ts]"]
  node_boardui["Board and table<br/>[Board.tsx]"]
  node_hud["HUD and lobby<br/>[Hud.tsx]"]
  node_events["Event playback<br/>[eventPlayer.ts]"]
  node_audio["Synthesized sound<br/>[sfx.ts]"]
  node_clientonline["Online transport<br/>[online.ts]"]
end

subgraph group_rules["Game engine"]
  node_game["Game orchestration<br/>[game.ts]"]
  node_legality["Chess legality<br/>[legality.ts]"]
  node_minefield["Mine placement<br/>[minefield.ts]"]
  node_reveal["Reveal cascade<br/>[reveal.ts]"]
  node_explosion["Chain explosions<br/>[explosion.ts]"]
  node_room["Room and clocks<br/>[room.ts]"]
end

subgraph group_opponents["AI opponent"]
  node_ai["Bot decisions<br/>[bot.ts]"]
  node_probability["Mine probabilities<br/>[probability.ts]"]
  node_search["Move search<br/>[search.ts]"]
end

subgraph group_online["Online play"]
  node_server["LAN server<br/>[server.ts]"]
  node_worker["Cloudflare Worker<br/>[index.ts]"]
  node_durable[("Room storage<br/>[index.ts]")]
end

node_player(("Player"))
node_opponent(("Online opponent"))

node_player -->|"chooses mode"| node_menu
node_menu -->|"selects screen"| node_app
node_menu -->|"starts or joins"| node_clientstate
node_app -->|"renders"| node_boardui
node_app -->|"renders"| node_hud
node_clientstate -->|"provides view"| node_boardui
node_clientstate -->|"submits moves"| node_game
node_game -->|"checks moves"| node_legality
node_game -->|"places mines"| node_minefield
node_game -->|"reveals cells"| node_reveal
node_game -->|"detonates mines"| node_explosion
node_game -->|"returns events"| node_clientstate
node_clientstate -->|"plays events"| node_events
node_events -->|"updates pieces"| node_boardui
node_events -->|"plays sounds"| node_audio
node_clientstate -.->|"requests move"| node_ai
node_ai -->|"infers mines"| node_probability
node_ai -->|"searches moves"| node_search
node_search -->|"generates moves"| node_legality
node_search -->|"scores risk"| node_probability
node_ai -.->|"returns move"| node_clientstate
node_clientstate -->|"sends intent"| node_clientonline
node_clientonline -.->|"WebSocket"| node_server
node_clientonline -->|"WebSocket"| node_worker
node_player -.->|"connects"| node_server
node_player -->|"connects"| node_worker
node_opponent -.->|"connects"| node_server
node_opponent -->|"connects"| node_worker
node_server -->|"handles room"| node_room
node_worker -->|"handles room"| node_room
node_room -->|"applies moves"| node_game
node_server -.->|"relays events"| node_clientonline
node_worker -->|"relays events"| node_clientonline
node_worker -->|"stores room"| node_durable

click node_menu "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Menu.tsx"
click node_app "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/App.tsx"
click node_clientstate "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/store.ts"
click node_boardui "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Board.tsx"
click node_hud "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Hud.tsx"
click node_events "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/anim/eventPlayer.ts"
click node_audio "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/sfx.ts"
click node_clientonline "https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/online.ts"
click node_game "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/game.ts"
click node_legality "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/legality.ts"
click node_minefield "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/minefield.ts"
click node_reveal "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/reveal.ts"
click node_explosion "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/explosion.ts"
click node_room "https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/room.ts"
click node_ai "https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/bot.ts"
click node_probability "https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/probability.ts"
click node_search "https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/search.ts"
click node_server "https://github.com/colochampre/chess-sweeper/blob/main/packages/server/src/server.ts"
click node_worker "https://github.com/colochampre/chess-sweeper/blob/main/packages/worker/src/index.ts"
click node_durable "https://github.com/colochampre/chess-sweeper/blob/main/packages/worker/src/index.ts"

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_menu,node_app,node_clientstate,node_boardui,node_hud,node_events,node_audio,node_clientonline toneBlue
class node_game,node_legality,node_minefield,node_reveal,node_explosion,node_room toneAmber
class node_ai,node_probability,node_search toneMint
class node_server,node_worker,node_durable toneRose
class node_player,node_opponent toneIndigo
```

## Components

### Player experience

- [Modes and setup](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Menu.tsx): `packages/client/src/components/Menu.tsx`
- [App shell](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/App.tsx): `packages/client/src/App.tsx`
- [Client game state](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/store.ts): `packages/client/src/store.ts`
- [Board and table](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Board.tsx): `packages/client/src/components/Board.tsx`
- [HUD and lobby](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/components/Hud.tsx): `packages/client/src/components/Hud.tsx`
- [Event playback](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/anim/eventPlayer.ts): `packages/client/src/anim/eventPlayer.ts`
- [Synthesized sound](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/sfx.ts): `packages/client/src/sfx.ts`
- [Online transport](https://github.com/colochampre/chess-sweeper/blob/main/packages/client/src/online.ts): `packages/client/src/online.ts`

### Game engine

- [Game orchestration](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/game.ts): `packages/engine/src/game.ts`
- [Chess legality](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/legality.ts): `packages/engine/src/legality.ts`
- [Mine placement](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/minefield.ts): `packages/engine/src/minefield.ts`
- [Reveal cascade](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/reveal.ts): `packages/engine/src/reveal.ts`
- [Chain explosions](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/explosion.ts): `packages/engine/src/explosion.ts`
- [Room and clocks](https://github.com/colochampre/chess-sweeper/blob/main/packages/engine/src/room.ts): `packages/engine/src/room.ts`

### AI opponent

- [Bot decisions](https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/bot.ts): `packages/ai/src/bot.ts`
- [Mine probabilities](https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/probability.ts): `packages/ai/src/probability.ts`
- [Move search](https://github.com/colochampre/chess-sweeper/blob/main/packages/ai/src/search.ts): `packages/ai/src/search.ts`

### Online play

- [LAN server](https://github.com/colochampre/chess-sweeper/blob/main/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Cloudflare Worker](https://github.com/colochampre/chess-sweeper/blob/main/packages/worker/src/index.ts): `packages/worker/src/index.ts`
- [Room storage](https://github.com/colochampre/chess-sweeper/blob/main/packages/worker/src/index.ts): `packages/worker/src/index.ts`

### Other components

- **Player**
- **Online opponent**

## Connections

- Player → Modes and setup: chooses mode
- Modes and setup → App shell: selects screen
- Modes and setup → Client game state: starts or joins
- App shell → Board and table: renders
- App shell → HUD and lobby: renders
- Client game state → Board and table: provides view
- Client game state → Game orchestration: submits moves
- Game orchestration → Chess legality: checks moves
- Game orchestration → Mine placement: places mines
- Game orchestration → Reveal cascade: reveals cells
- Game orchestration → Chain explosions: detonates mines
- Game orchestration → Client game state: returns events
- Client game state → Event playback: plays events
- Event playback → Board and table: updates pieces
- Event playback → Synthesized sound: plays sounds
- Client game state → Bot decisions: requests move
- Bot decisions → Mine probabilities: infers mines
- Bot decisions → Move search: searches moves
- Move search → Chess legality: generates moves
- Move search → Mine probabilities: scores risk
- Bot decisions → Client game state: returns move
- Client game state → Online transport: sends intent
- Online transport → LAN server: WebSocket
- Online transport → Cloudflare Worker: WebSocket
- Player → LAN server: connects
- Player → Cloudflare Worker: connects
- Online opponent → LAN server: connects
- Online opponent → Cloudflare Worker: connects
- LAN server → Room and clocks: handles room
- Cloudflare Worker → Room and clocks: handles room
- Room and clocks → Game orchestration: applies moves
- LAN server → Online transport: relays events
- Cloudflare Worker → Online transport: relays events
- Cloudflare Worker → Room storage: stores room