# auriny/chess-capital architecture

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

## Overview

ChessCapital turns camera frames into recognized board states, then uses chess rules to infer and validate moves against a persisted game. The CV service posts recognized state to the game backend; the frontend is a lightweight interface. The graph preserves the documented recognition, move-validation, illegal-move, and streaming capabilities. Some frontend and stream integrations are documented but their runtime wiring is not shown in the sampled source, so those links are marked unverified or omitted.

Main entry points: [`game-service/routers/v1/game_process.py`](https://github.com/auriny/chess-capital/blob/main/game-service/routers/v1/game_process.py) (Game API), [`cv-service/routers/frame.py`](https://github.com/auriny/chess-capital/blob/main/cv-service/routers/frame.py) (Frame API), [`game-service/utils/chess_facade.py`](https://github.com/auriny/chess-capital/blob/main/game-service/utils/chess_facade.py) (Chess Rules Facade), [`game-service/main.py`](https://github.com/auriny/chess-capital/blob/main/game-service/main.py) (API Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["Web Interface<br/>[index.html]"]
  node_admin["Admin Interface<br/>[admin.html]"]
end

subgraph group_vision["Vision Service"]
  node_cv_api["Frame API<br/>[frame.py]"]
  node_frame_decode["Frame Decoder<br/>[utils.py]"]
  node_recognizer["Board Recognizer<br/>[recognizer.py]"]
  node_cv_config["CV Configuration<br/>[config.py]"]
end

subgraph group_game["Game Backend"]
  node_game_api["Game API<br/>[game_process.py]"]
  node_move_api["Move API<br/>[send_move.py]"]
  node_game_models["Game Models<br/>[requests.py]"]
  node_chess["Chess Rules Facade<br/>[chess_facade.py]"]
  node_game_state[("PGN Game Files<br/>[config.py]")]
  node_exceptions["Domain Errors"]
  node_startup["Service Startup<br/>[startup.py]"]
  node_api_setup["API Setup<br/>[main.py]"]
end

subgraph group_integrations["Game Integrations"]
  node_lichess["Lichess Stream<br/>[lichess_stream.py]"]
  node_vk_stream["VK Video Stream"]
end

node_camera(("Phone Camera"))

node_camera -.->|"captures frames"| node_frontend
node_frontend -.->|"submits frames"| node_cv_api
node_cv_api -->|"decodes frame"| node_frame_decode
node_cv_api -->|"recognizes board"| node_recognizer
node_cv_api -->|"uses host config"| node_cv_config
node_cv_api -->|"posts board state"| node_move_api
node_frontend -.->|"uses game API"| node_game_api
node_game_api -->|"creates and loads games"| node_chess
node_game_api -->|"starts stream"| node_lichess
node_game_api -->|"validates start data"| node_game_models
node_chess -.->|"reads and writes PGN"| node_game_state
node_chess -->|"sends PGN"| node_lichess
node_chess -->|"raises domain errors"| node_exceptions
node_api_setup -->|"configures lifespan"| node_startup
node_api_setup -->|"registers handlers"| node_exceptions
node_api_setup -.->|"mounts routes"| node_game_api
node_vk_stream -.->|"provides stream URL"| node_game_api

click node_frontend "https://github.com/auriny/chess-capital/blob/main/frontend/index.html"
click node_admin "https://github.com/auriny/chess-capital/blob/main/frontend/admin.html"
click node_cv_api "https://github.com/auriny/chess-capital/blob/main/cv-service/routers/frame.py"
click node_frame_decode "https://github.com/auriny/chess-capital/blob/main/cv-service/utils.py"
click node_recognizer "https://github.com/auriny/chess-capital/blob/main/cv-service/recognizer.py"
click node_cv_config "https://github.com/auriny/chess-capital/blob/main/cv-service/config.py"
click node_game_api "https://github.com/auriny/chess-capital/blob/main/game-service/routers/v1/game_process.py"
click node_move_api "https://github.com/auriny/chess-capital/blob/main/game-service/routers/v1/send_move.py"
click node_game_models "https://github.com/auriny/chess-capital/blob/main/game-service/models/requests.py"
click node_chess "https://github.com/auriny/chess-capital/blob/main/game-service/utils/chess_facade.py"
click node_game_state "https://github.com/auriny/chess-capital/blob/main/game-service/config.py"
click node_exceptions "https://github.com/auriny/chess-capital/tree/main/game-service/exceptions"
click node_startup "https://github.com/auriny/chess-capital/blob/main/game-service/utils/startup.py"
click node_api_setup "https://github.com/auriny/chess-capital/blob/main/game-service/main.py"
click node_lichess "https://github.com/auriny/chess-capital/blob/main/game-service/utils/lichess_stream.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_frontend,node_admin toneBlue
class node_cv_api,node_frame_decode,node_recognizer,node_cv_config toneAmber
class node_game_api,node_move_api,node_game_models,node_chess,node_game_state,node_exceptions,node_startup,node_api_setup toneMint
class node_lichess,node_vk_stream toneRose
class node_camera toneIndigo
```

## Components

### Client

- [Web Interface](https://github.com/auriny/chess-capital/blob/main/frontend/index.html): `frontend/index.html`
- [Admin Interface](https://github.com/auriny/chess-capital/blob/main/frontend/admin.html): `frontend/admin.html`

### Vision Service

- [Frame API](https://github.com/auriny/chess-capital/blob/main/cv-service/routers/frame.py): `cv-service/routers/frame.py`
- [Frame Decoder](https://github.com/auriny/chess-capital/blob/main/cv-service/utils.py): `cv-service/utils.py`
- [Board Recognizer](https://github.com/auriny/chess-capital/blob/main/cv-service/recognizer.py): `cv-service/recognizer.py`
- [CV Configuration](https://github.com/auriny/chess-capital/blob/main/cv-service/config.py): `cv-service/config.py`

### Game Backend

- [Game API](https://github.com/auriny/chess-capital/blob/main/game-service/routers/v1/game_process.py): `game-service/routers/v1/game_process.py`
- [Move API](https://github.com/auriny/chess-capital/blob/main/game-service/routers/v1/send_move.py): `game-service/routers/v1/send_move.py`
- [Game Models](https://github.com/auriny/chess-capital/blob/main/game-service/models/requests.py): `game-service/models/requests.py`
- [Chess Rules Facade](https://github.com/auriny/chess-capital/blob/main/game-service/utils/chess_facade.py): `game-service/utils/chess_facade.py`
- [PGN Game Files](https://github.com/auriny/chess-capital/blob/main/game-service/config.py): `game-service/config.py`
- [Domain Errors](https://github.com/auriny/chess-capital/tree/main/game-service/exceptions): `game-service/exceptions`
- [Service Startup](https://github.com/auriny/chess-capital/blob/main/game-service/utils/startup.py): `game-service/utils/startup.py`
- [API Setup](https://github.com/auriny/chess-capital/blob/main/game-service/main.py): `game-service/main.py`

### Game Integrations

- [Lichess Stream](https://github.com/auriny/chess-capital/blob/main/game-service/utils/lichess_stream.py): `game-service/utils/lichess_stream.py`
- **VK Video Stream**

### Other components

- **Phone Camera**

## Connections

- Phone Camera → Web Interface: captures frames
- Web Interface → Frame API: submits frames
- Frame API → Frame Decoder: decodes frame (evidence: `cv-service/routers/frame.py`)
- Frame API → Board Recognizer: recognizes board (evidence: `cv-service/routers/frame.py`)
- Frame API → CV Configuration: uses host config (evidence: `cv-service/routers/frame.py`)
- Frame API → Move API: posts board state (evidence: `cv-service/routers/frame.py`)
- Web Interface → Game API: uses game API
- Game API → Chess Rules Facade: creates and loads games (evidence: `game-service/routers/v1/game_process.py`)
- Game API → Lichess Stream: starts stream (evidence: `game-service/routers/v1/game_process.py`)
- Game API → Game Models: validates start data (evidence: `game-service/routers/v1/game_process.py`)
- Chess Rules Facade → PGN Game Files: reads and writes PGN
- Chess Rules Facade → Lichess Stream: sends PGN (evidence: `game-service/utils/chess_facade.py`)
- Chess Rules Facade → Domain Errors: raises domain errors (evidence: `game-service/utils/chess_facade.py`)
- API Setup → Service Startup: configures lifespan (evidence: `game-service/main.py`)
- API Setup → Domain Errors: registers handlers (evidence: `game-service/main.py`)
- API Setup → Game API: mounts routes
- VK Video Stream → Game API: provides stream URL
