# vd-phuc-2k5/chessgame architecture

> Architecture diagram of the GitHub repository vd-phuc-2k5/chessgame, 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/vd-phuc-2k5/chessgame
- Repository: https://github.com/vd-phuc-2k5/chessgame

## Overview

ChessGame is a browser-based chess app with a TypeScript rules engine and optional Stockfish opponent. The main workflow runs from board interaction through GameController into the domain Game, which validates and applies moves, records notation/history and updates state; the controller publishes snapshots for the UI. In engine mode, the strategy requests a move from the API route and converts its UCI response. Edges reflect the README and shown calls/imports; unsampled UI and engine wiring is represented only where documented.

Main entry points: [`packages/domain/src/lib/game/game.ts`](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/game.ts) (Game rules facade), [`client/src/game/gameController.ts`](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/gameController.ts) (Game controller), [`client/src/components/board/board.tsx`](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/board.tsx) (Board view), [`client/src/game/playerStrategy.ts`](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/playerStrategy.ts) (Engine strategy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Board UI"]
  node_board["Board view<br/>[board.tsx]"]
  node_grid["Board grid<br/>[boardGrid.tsx]"]
  node_promotion["Promotion choice"]
  node_overlays["Game overlays<br/>[gameOverlay.tsx]"]
  node_controls["Game controls<br/>[gameControls.tsx]"]
  node_historyui["Move history UI"]
  node_orientation["Board orientation"]
end

subgraph group_app["Game orchestration"]
  node_controller["Game controller<br/>[gameController.ts]"]
  node_hook["Snapshot hook"]
  node_clock["Game clock<br/>[gameClock.ts]"]
  node_strategy["Player strategy<br/>[playerStrategy.ts]"]
end

subgraph group_rules["Chess domain"]
  node_game["Game rules facade<br/>[game.ts]"]
  node_boardstate["Board state<br/>[board.ts]"]
  node_pieces["Piece creation<br/>[pieceFactory.ts]"]
  node_moves["Move generation<br/>[moveGenerator.ts]"]
  node_validation["Move validation<br/>[moveValidator.ts]"]
  node_execution["Move execution"]
  node_state["Game state<br/>[gameState.ts]"]
  node_stateupdate["State updater"]
  node_history["Move history<br/>[moveHistory.ts]"]
  node_notation["Notation and PGN"]
  node_position["Position model<br/>[position.ts]"]
end

subgraph group_engine["Computer opponent"]
  node_engineplayer["Engine strategy<br/>[playerStrategy.ts]"]
  node_stockfish["Engine client<br/>[stockfishEngine.ts]"]
  node_uci["UCI conversion<br/>[uci.ts]"]
  node_endpoint["Engine API<br/>[route.ts]"]
  node_binary["Stockfish process"]
end

subgraph group_contracts["Core contracts"]
  node_contracts["Chess contracts<br/>[iGameState.ts]"]
end

node_player(("Player"))

node_player -->|"interacts with"| node_board
node_board -->|"renders"| node_grid
node_board -->|"renders"| node_promotion
node_board -->|"renders"| node_overlays
node_board -.->|"configures"| node_orientation
node_board -.->|"offers"| node_controls
node_board -.->|"shows"| node_historyui
node_board -->|"sends moves"| node_controller
node_promotion -->|"chooses piece"| node_controller
node_controller -->|"requests legal moves"| node_game
node_controller -->|"executes move"| node_game
node_controller -->|"starts and ticks"| node_clock
node_controller -->|"creates player"| node_strategy
node_hook -->|"subscribes"| node_controller
node_controller -->|"publishes snapshot"| node_hook
node_game -->|"reads and resets"| node_boardstate
node_boardstate -->|"creates pieces"| node_pieces
node_game -->|"generates candidates"| node_moves
node_game -->|"checks legality"| node_validation
node_game -->|"selects executor"| node_execution
node_game -->|"updates state"| node_stateupdate
node_stateupdate -->|"updates"| node_state
node_game -->|"builds notation"| node_notation
node_game -->|"records moves"| node_history
node_notation -->|"finds alternatives"| node_moves
node_moves -->|"reads board"| node_boardstate
node_game -->|"uses coordinates"| node_position
node_game -.->|"implements contracts"| node_contracts
node_controller -->|"creates engine player"| node_engineplayer
node_engineplayer -.->|"requests move"| node_stockfish
node_stockfish -->|"posts UCI moves"| node_endpoint
node_endpoint -->|"spawns process"| node_binary
node_engineplayer -.->|"converts move"| node_uci
node_uci -.->|"returns move"| node_controller

click node_board "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/board.tsx"
click node_grid "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/boardGrid.tsx"
click node_promotion "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/promotionOverlay.tsx"
click node_overlays "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/gameOverlay.tsx"
click node_controls "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/gameControls.tsx"
click node_historyui "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/moveHistoryPanel.tsx"
click node_orientation "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/boardOrientation.tsx"
click node_controller "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/gameController.ts"
click node_hook "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/useGameController.ts"
click node_clock "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/gameClock.ts"
click node_strategy "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/playerStrategy.ts"
click node_game "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/game.ts"
click node_boardstate "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/board/board.ts"
click node_pieces "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/piece/pieceFactory.ts"
click node_moves "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/move/moveGenerator.ts"
click node_validation "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/move/moveValidator.ts"
click node_execution "https://github.com/vd-phuc-2k5/chessgame/tree/main/packages/domain/src/lib/execution"
click node_state "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/gameState.ts"
click node_stateupdate "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/gameStateUpdater.ts"
click node_history "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/history/moveHistory.ts"
click node_notation "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/history/moveNotationBuilder.ts"
click node_position "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/position/position.ts"
click node_contracts "https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/core/src/lib/interfaces/iGameState.ts"
click node_engineplayer "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/playerStrategy.ts"
click node_stockfish "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/stockfishEngine.ts"
click node_uci "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/uci.ts"
click node_endpoint "https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/app/api/engine/route.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_board,node_grid,node_promotion,node_overlays,node_controls,node_historyui,node_orientation toneBlue
class node_controller,node_hook,node_clock,node_strategy toneAmber
class node_game,node_boardstate,node_pieces,node_moves,node_validation,node_execution,node_state,node_stateupdate,node_history,node_notation,node_position toneMint
class node_engineplayer,node_stockfish,node_uci,node_endpoint,node_binary toneRose
class node_contracts,node_player toneIndigo
```

## Components

### Board UI

- [Board view](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/board.tsx): `client/src/components/board/board.tsx`
- [Board grid](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/boardGrid.tsx): `client/src/components/board/boardGrid.tsx`
- [Promotion choice](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/promotionOverlay.tsx): `client/src/components/board/promotionOverlay.tsx`
- [Game overlays](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/gameOverlay.tsx): `client/src/components/board/gameOverlay.tsx`
- [Game controls](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/gameControls.tsx): `client/src/components/board/gameControls.tsx`
- [Move history UI](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/moveHistoryPanel.tsx): `client/src/components/board/moveHistoryPanel.tsx`
- [Board orientation](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/components/board/boardOrientation.tsx): `client/src/components/board/boardOrientation.tsx`

### Game orchestration

- [Game controller](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/gameController.ts): `client/src/game/gameController.ts`
- [Snapshot hook](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/useGameController.ts): `client/src/game/useGameController.ts`
- [Game clock](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/gameClock.ts): `client/src/game/gameClock.ts`
- [Player strategy](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/playerStrategy.ts): `client/src/game/playerStrategy.ts`

### Chess domain

- [Game rules facade](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/game.ts): `packages/domain/src/lib/game/game.ts`
- [Board state](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/board/board.ts): `packages/domain/src/lib/board/board.ts`
- [Piece creation](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/piece/pieceFactory.ts): `packages/domain/src/lib/piece/pieceFactory.ts`
- [Move generation](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/move/moveGenerator.ts): `packages/domain/src/lib/move/moveGenerator.ts`
- [Move validation](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/move/moveValidator.ts): `packages/domain/src/lib/move/moveValidator.ts`
- [Move execution](https://github.com/vd-phuc-2k5/chessgame/tree/main/packages/domain/src/lib/execution): `packages/domain/src/lib/execution`
- [Game state](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/gameState.ts): `packages/domain/src/lib/game/gameState.ts`
- [State updater](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/game/gameStateUpdater.ts): `packages/domain/src/lib/game/gameStateUpdater.ts`
- [Move history](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/history/moveHistory.ts): `packages/domain/src/lib/history/moveHistory.ts`
- [Notation and PGN](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/history/moveNotationBuilder.ts): `packages/domain/src/lib/history/moveNotationBuilder.ts`
- [Position model](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/domain/src/lib/position/position.ts): `packages/domain/src/lib/position/position.ts`

### Computer opponent

- [Engine strategy](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/playerStrategy.ts): `client/src/game/playerStrategy.ts`
- [Engine client](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/stockfishEngine.ts): `client/src/game/stockfishEngine.ts`
- [UCI conversion](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/game/uci.ts): `client/src/game/uci.ts`
- [Engine API](https://github.com/vd-phuc-2k5/chessgame/blob/main/client/src/app/api/engine/route.ts): `client/src/app/api/engine/route.ts`
- **Stockfish process**

### Core contracts

- [Chess contracts](https://github.com/vd-phuc-2k5/chessgame/blob/main/packages/core/src/lib/interfaces/iGameState.ts): `packages/core/src/lib/interfaces/iGameState.ts`

### Other components

- **Player**

## Connections

- Player → Board view: interacts with
- Board view → Board grid: renders (evidence: `client/src/components/board/board.tsx`)
- Board view → Promotion choice: renders (evidence: `client/src/components/board/board.tsx`)
- Board view → Game overlays: renders (evidence: `client/src/components/board/board.tsx`)
- Board view → Board orientation: configures
- Board view → Game controls: offers
- Board view → Move history UI: shows
- Board view → Game controller: sends moves
- Promotion choice → Game controller: chooses piece
- Game controller → Game rules facade: requests legal moves (evidence: `client/src/game/gameController.ts`)
- Game controller → Game rules facade: executes move
- Game controller → Game clock: starts and ticks (evidence: `client/src/game/gameController.ts`)
- Game controller → Player strategy: creates player (evidence: `client/src/game/gameController.ts`)
- Snapshot hook → Game controller: subscribes (evidence: `client/src/game/useGameController.ts`)
- Game controller → Snapshot hook: publishes snapshot (evidence: `client/src/game/useGameController.ts`)
- Game rules facade → Board state: reads and resets (evidence: `packages/domain/src/lib/game/game.ts`)
- Board state → Piece creation: creates pieces (evidence: `packages/domain/src/lib/board/board.ts`)
- Game rules facade → Move generation: generates candidates (evidence: `packages/domain/src/lib/game/game.ts`)
- Game rules facade → Move validation: checks legality (evidence: `packages/domain/src/lib/game/game.ts`)
- Game rules facade → Move execution: selects executor (evidence: `packages/domain/src/lib/game/game.ts`)
- Game rules facade → State updater: updates state (evidence: `packages/domain/src/lib/game/game.ts`)
- State updater → Game state: updates (evidence: `packages/domain/src/lib/game/gameStateUpdater.ts`)
- Game rules facade → Notation and PGN: builds notation (evidence: `packages/domain/src/lib/game/game.ts`)
- Game rules facade → Move history: records moves (evidence: `packages/domain/src/lib/game/game.ts`)
- Notation and PGN → Move generation: finds alternatives (evidence: `packages/domain/src/lib/history/moveNotationBuilder.ts`)
- Move generation → Board state: reads board (evidence: `packages/domain/src/lib/move/moveGenerator.ts`)
- Game rules facade → Position model: uses coordinates (evidence: `packages/domain/src/lib/game/game.ts`)
- Game rules facade → Chess contracts: implements contracts (evidence: `packages/domain/src/lib/game/game.ts`)
- Game controller → Engine strategy: creates engine player (evidence: `client/src/game/gameController.ts`)
- Engine strategy → Engine client: requests move
- Engine client → Engine API: posts UCI moves (evidence: `client/src/game/stockfishEngine.ts`)
- Engine API → Stockfish process: spawns process
- Engine strategy → UCI conversion: converts move
- UCI conversion → Game controller: returns move
