# therealnightmare/playerkoi architecture

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

- Interactive diagram: https://gitdiagram.com/therealnightmare/playerkoi
- Repository: https://github.com/therealnightmare/playerkoi

## Overview

Player Koi tracks a physical chessboard: calibrated camera frames pass through motion gating and occupancy classification, then legal-move resolution updates a software chess position. The web UI exposes ordinary play, engine opponent, guided coaching, puzzles, and manual correction; an optional gantry executes moves. The graph emphasizes the documented runtime flow and major modes. Some mode and integration links rely on README or web_ui.py references; unsampled implementation details are not inferred.

Main entry points: [`src/web_ui.py`](https://github.com/therealnightmare/playerkoi/blob/main/src/web_ui.py) (Web UI server), [`src/tracking_loop.py`](https://github.com/therealnightmare/playerkoi/blob/main/src/tracking_loop.py) (Board tracking), [`src/robot.py`](https://github.com/therealnightmare/playerkoi/blob/main/src/robot.py) (Robot controller), [`src/engine.py`](https://github.com/therealnightmare/playerkoi/blob/main/src/engine.py) (Chess engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vision and tracking"]
  node_camera["Camera capture<br/>[capture.py]"]
  node_calibration["Board calibration<br/>[calibrate.py]"]
  node_geometry["Square geometry<br/>[square_geometry.py]"]
  node_classifier["Occupancy classifier"]
  node_motion["Motion gate<br/>[roi_diff.py]"]
  node_tracking["Board tracking<br/>[tracking_loop.py]"]
  node_resolver["Legal move resolver<br/>[move_resolver.py]"]
  node_board["Board state<br/>[board_state.py]"]
end

subgraph group_play["Game modes"]
  node_engine["Chess engine<br/>[engine.py]"]
  node_coach["Guided coach<br/>[coach.py]"]
  node_policy["Move policy<br/>[move_policy.py]"]
  node_puzzles["Puzzle mode<br/>[puzzles.py]"]
end

subgraph group_gantry["Robot gantry"]
  node_robot_controller["Robot controller<br/>[robot.py]"]
  node_planner["Move planner<br/>[robot_moves.py]"]
  node_rig["Rig geometry<br/>[rig.py]"]
end

subgraph group_interface["Web interface"]
  node_web["Web UI server<br/>[web_ui.py]"]
  node_session["Mode session<br/>[session.py]"]
  node_browser["Browser controls<br/>[app.js]"]
  node_admin["Manual administration<br/>[admin_moves.py]"]
end

node_player(("Player"))
node_stockfish["Stockfish"]
node_gantry_device["Gantry hardware"]

node_player -->|"operates"| node_browser
node_browser -.->|"sends controls"| node_web
node_web -->|"manages modes"| node_session
node_web -->|"serves tracking"| node_tracking
node_camera -->|"supplies frames"| node_tracking
node_calibration -.->|"sets board mapping"| node_geometry
node_tracking -->|"gates detection"| node_motion
node_tracking -->|"classifies squares"| node_classifier
node_tracking -->|"uses square boxes"| node_geometry
node_tracking -->|"resolves deltas"| node_resolver
node_resolver -->|"updates position"| node_board
node_web -->|"creates opponent"| node_engine
node_engine -->|"uses UCI"| node_stockfish
node_web -->|"provides guided mode"| node_coach
node_coach -->|"requests analysis"| node_engine
node_web -->|"provides puzzles"| node_puzzles
node_web -->|"selects move policy"| node_policy
node_web -->|"dispatches moves"| node_robot_controller
node_robot_controller -->|"plans motion"| node_planner
node_planner -->|"uses measured geometry"| node_rig
node_robot_controller -.->|"sends commands"| node_gantry_device
node_web -->|"offers corrections"| node_admin
node_admin -->|"controls arm"| node_robot_controller

click node_camera "https://github.com/therealnightmare/playerkoi/blob/main/src/capture.py"
click node_calibration "https://github.com/therealnightmare/playerkoi/blob/main/src/calibrate.py"
click node_geometry "https://github.com/therealnightmare/playerkoi/blob/main/src/square_geometry.py"
click node_classifier "https://github.com/therealnightmare/playerkoi/blob/main/src/square_classifier.py"
click node_motion "https://github.com/therealnightmare/playerkoi/blob/main/src/roi_diff.py"
click node_tracking "https://github.com/therealnightmare/playerkoi/blob/main/src/tracking_loop.py"
click node_resolver "https://github.com/therealnightmare/playerkoi/blob/main/src/move_resolver.py"
click node_board "https://github.com/therealnightmare/playerkoi/blob/main/src/board_state.py"
click node_web "https://github.com/therealnightmare/playerkoi/blob/main/src/web_ui.py"
click node_session "https://github.com/therealnightmare/playerkoi/blob/main/src/session.py"
click node_browser "https://github.com/therealnightmare/playerkoi/blob/main/src/ui/app.js"
click node_engine "https://github.com/therealnightmare/playerkoi/blob/main/src/engine.py"
click node_coach "https://github.com/therealnightmare/playerkoi/blob/main/src/coach.py"
click node_policy "https://github.com/therealnightmare/playerkoi/blob/main/src/move_policy.py"
click node_puzzles "https://github.com/therealnightmare/playerkoi/blob/main/src/puzzles.py"
click node_robot_controller "https://github.com/therealnightmare/playerkoi/blob/main/src/robot.py"
click node_planner "https://github.com/therealnightmare/playerkoi/blob/main/src/robot_moves.py"
click node_rig "https://github.com/therealnightmare/playerkoi/blob/main/src/rig.py"
click node_admin "https://github.com/therealnightmare/playerkoi/blob/main/src/admin_moves.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_camera,node_calibration,node_geometry,node_classifier,node_motion,node_tracking,node_resolver,node_board toneBlue
class node_engine,node_coach,node_policy,node_puzzles toneAmber
class node_robot_controller,node_planner,node_rig toneMint
class node_web,node_session,node_browser,node_admin toneRose
class node_player,node_stockfish,node_gantry_device toneIndigo
```

## Components

### Vision and tracking

- [Camera capture](https://github.com/therealnightmare/playerkoi/blob/main/src/capture.py): `src/capture.py`
- [Board calibration](https://github.com/therealnightmare/playerkoi/blob/main/src/calibrate.py): `src/calibrate.py`
- [Square geometry](https://github.com/therealnightmare/playerkoi/blob/main/src/square_geometry.py): `src/square_geometry.py`
- [Occupancy classifier](https://github.com/therealnightmare/playerkoi/blob/main/src/square_classifier.py): `src/square_classifier.py`
- [Motion gate](https://github.com/therealnightmare/playerkoi/blob/main/src/roi_diff.py): `src/roi_diff.py`
- [Board tracking](https://github.com/therealnightmare/playerkoi/blob/main/src/tracking_loop.py): `src/tracking_loop.py`
- [Legal move resolver](https://github.com/therealnightmare/playerkoi/blob/main/src/move_resolver.py): `src/move_resolver.py`
- [Board state](https://github.com/therealnightmare/playerkoi/blob/main/src/board_state.py): `src/board_state.py`

### Game modes

- [Chess engine](https://github.com/therealnightmare/playerkoi/blob/main/src/engine.py): `src/engine.py`
- [Guided coach](https://github.com/therealnightmare/playerkoi/blob/main/src/coach.py): `src/coach.py`
- [Move policy](https://github.com/therealnightmare/playerkoi/blob/main/src/move_policy.py): `src/move_policy.py`
- [Puzzle mode](https://github.com/therealnightmare/playerkoi/blob/main/src/puzzles.py): `src/puzzles.py`

### Robot gantry

- [Robot controller](https://github.com/therealnightmare/playerkoi/blob/main/src/robot.py): `src/robot.py`
- [Move planner](https://github.com/therealnightmare/playerkoi/blob/main/src/robot_moves.py): `src/robot_moves.py`
- [Rig geometry](https://github.com/therealnightmare/playerkoi/blob/main/src/rig.py): `src/rig.py`

### Web interface

- [Web UI server](https://github.com/therealnightmare/playerkoi/blob/main/src/web_ui.py): `src/web_ui.py`
- [Mode session](https://github.com/therealnightmare/playerkoi/blob/main/src/session.py): `src/session.py`
- [Browser controls](https://github.com/therealnightmare/playerkoi/blob/main/src/ui/app.js): `src/ui/app.js`
- [Manual administration](https://github.com/therealnightmare/playerkoi/blob/main/src/admin_moves.py): `src/admin_moves.py`

### Other components

- **Player**
- **Stockfish**
- **Gantry hardware**

## Connections

- Player → Browser controls: operates
- Browser controls → Web UI server: sends controls
- Web UI server → Mode session: manages modes (evidence: `src/web_ui.py`)
- Web UI server → Board tracking: serves tracking (evidence: `src/web_ui.py`)
- Camera capture → Board tracking: supplies frames (evidence: `src/main.py`)
- Board calibration → Square geometry: sets board mapping
- Board tracking → Motion gate: gates detection (evidence: `src/tracking_loop.py`)
- Board tracking → Occupancy classifier: classifies squares (evidence: `src/tracking_loop.py`)
- Board tracking → Square geometry: uses square boxes (evidence: `src/tracking_loop.py`)
- Board tracking → Legal move resolver: resolves deltas (evidence: `src/tracking_loop.py`)
- Legal move resolver → Board state: updates position (evidence: `src/board_state.py`)
- Web UI server → Chess engine: creates opponent (evidence: `src/web_ui.py`)
- Chess engine → Stockfish: uses UCI (evidence: `src/engine.py`)
- Web UI server → Guided coach: provides guided mode (evidence: `src/web_ui.py`)
- Guided coach → Chess engine: requests analysis (evidence: `src/coach.py`)
- Web UI server → Puzzle mode: provides puzzles (evidence: `src/web_ui.py`)
- Web UI server → Move policy: selects move policy (evidence: `src/web_ui.py`)
- Web UI server → Robot controller: dispatches moves (evidence: `src/web_ui.py`)
- Robot controller → Move planner: plans motion (evidence: `src/robot.py`)
- Move planner → Rig geometry: uses measured geometry (evidence: `src/robot_moves.py`)
- Robot controller → Gantry hardware: sends commands
- Web UI server → Manual administration: offers corrections (evidence: `src/web_ui.py`)
- Manual administration → Robot controller: controls arm (evidence: `src/admin_moves.py`)
