# august0362/btl_ai architecture

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

- Interactive diagram: https://gitdiagram.com/august0362/btl_ai
- Repository: https://github.com/august0362/btl_ai

## Overview

Chess AI Tournament is a desktop chess game where a person can play an AI or run bot-versus-bot matches, then inspect game history and player rankings. The main path is GUI input → controller → match runner → player move selection and game-state updates → recorded result, with history and Elo statistics available afterward. The README names four AI approaches; their modules are represented, but unsampled implementation details and wiring are not asserted. Edges reflect shown excerpts, SOURCE INDEX references, or README statements; uncertain links are omitted or dashed.

Main entry points: [`frontend/gui/app.py`](https://github.com/august0362/btl_ai/blob/main/frontend/gui/app.py) (Screen manager), [`frontend/gui/controller.py`](https://github.com/august0362/btl_ai/blob/main/frontend/gui/controller.py) (Game controller), [`backend/ai/base_bot.py`](https://github.com/august0362/btl_ai/blob/main/backend/ai/base_bot.py) (Bot interface), [`backend/tournament/match_runner.py`](https://github.com/august0362/btl_ai/blob/main/backend/tournament/match_runner.py) (Match runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_launcher["Application launch<br/>[main.py]"]
  node_app["Screen manager<br/>[app.py]"]
  node_screens["Game and menu screens"]
  node_controller["Game controller<br/>[controller.py]"]
  node_board["Board view<br/>[board_view.py]"]
  node_renderer["GUI renderer<br/>[render.py]"]
  node_themes["Themes and styling<br/>[theme.py]"]
end

subgraph group_match["Match runtime"]
  node_matchrunner["Match runner<br/>[match_runner.py]"]
  node_players["Player interface<br/>[players.py]"]
  node_state["Chess game state<br/>[game_state.py]"]
  node_types["Game and move types<br/>[types.py]"]
end

subgraph group_agents["AI players"]
  node_registry["Bot registry<br/>[registry.py]"]
  node_basebot["Bot interface<br/>[base_bot.py]"]
  node_regression["Regression alpha-beta<br/>[bot.py]"]
  node_genetic["Genetic alpha-beta"]
  node_mcts["Pure MCTS<br/>[bot.py]"]
  node_random["Random bot<br/>[bot.py]"]
end

subgraph group_results["Records and rankings"]
  node_records["Game records<br/>[records.py]"]
  node_history[("Game history<br/>[history.py]")]
  node_ranking[("Elo ranking<br/>[ranking.py]")]
  node_series["Match series<br/>[series.py]"]
end

subgraph group_training["DQN learning"]
  node_dqn["Deep RL bot<br/>[bot.py]"]
  node_dqnlearn["DQN training and evaluation"]
end

node_person(("Player"))

node_person -->|"chooses moves"| node_screens
node_launcher -->|"launches"| node_app
node_app -->|"routes screens"| node_screens
node_screens -->|"reads snapshots"| node_controller
node_screens -->|"uses board view"| node_board
node_board -->|"draws through"| node_renderer
node_renderer -->|"uses theme"| node_themes
node_app -->|"creates controller"| node_controller
node_controller -->|"runs matches"| node_matchrunner
node_controller -->|"wraps players"| node_players
node_matchrunner -->|"requests moves"| node_players
node_matchrunner -->|"updates game"| node_state
node_matchrunner -->|"builds record"| node_records
node_state -->|"uses game types"| node_types
node_records -->|"stores result types"| node_types
node_app -->|"lists bots"| node_registry
node_registry -->|"uses bot interface"| node_basebot
node_regression -.->|"implements interface"| node_basebot
node_genetic -.->|"implements interface"| node_basebot
node_mcts -.->|"implements interface"| node_basebot
node_random -->|"implements interface"| node_basebot
node_dqn -.->|"implements interface"| node_basebot
node_dqnlearn -.->|"trains policy"| node_dqn
node_controller -->|"supplies history"| node_history
node_controller -->|"supplies ranking"| node_ranking
node_history -->|"loads records"| node_records
node_ranking -->|"rates results"| node_records
node_series -->|"runs games"| node_matchrunner
node_series -->|"uses players"| node_players
node_series -->|"collects records"| node_records
node_app -->|"loads replay"| node_history
node_app -->|"creates ranking"| node_ranking

click node_launcher "https://github.com/august0362/btl_ai/blob/main/main.py"
click node_app "https://github.com/august0362/btl_ai/blob/main/frontend/gui/app.py"
click node_screens "https://github.com/august0362/btl_ai/tree/main/frontend/gui/screens"
click node_controller "https://github.com/august0362/btl_ai/blob/main/frontend/gui/controller.py"
click node_board "https://github.com/august0362/btl_ai/blob/main/frontend/gui/widgets/board_view.py"
click node_renderer "https://github.com/august0362/btl_ai/blob/main/frontend/gui/render.py"
click node_themes "https://github.com/august0362/btl_ai/blob/main/frontend/gui/theme.py"
click node_matchrunner "https://github.com/august0362/btl_ai/blob/main/backend/tournament/match_runner.py"
click node_players "https://github.com/august0362/btl_ai/blob/main/backend/tournament/players.py"
click node_state "https://github.com/august0362/btl_ai/blob/main/backend/core/game_state.py"
click node_types "https://github.com/august0362/btl_ai/blob/main/backend/core/types.py"
click node_registry "https://github.com/august0362/btl_ai/blob/main/backend/ai/registry.py"
click node_basebot "https://github.com/august0362/btl_ai/blob/main/backend/ai/base_bot.py"
click node_regression "https://github.com/august0362/btl_ai/blob/main/backend/ai/alphabeta_regression/bot.py"
click node_genetic "https://github.com/august0362/btl_ai/tree/main/backend/ai/genetic_alphabeta"
click node_mcts "https://github.com/august0362/btl_ai/blob/main/backend/ai/mcts/bot.py"
click node_random "https://github.com/august0362/btl_ai/blob/main/backend/ai/random_bot/bot.py"
click node_dqn "https://github.com/august0362/btl_ai/blob/main/backend/ai/deep_rl/bot.py"
click node_dqnlearn "https://github.com/august0362/btl_ai/tree/main/backend/ai/deep_rl/user"
click node_records "https://github.com/august0362/btl_ai/blob/main/backend/tournament/records.py"
click node_history "https://github.com/august0362/btl_ai/blob/main/backend/tournament/history.py"
click node_ranking "https://github.com/august0362/btl_ai/blob/main/backend/tournament/ranking.py"
click node_series "https://github.com/august0362/btl_ai/blob/main/backend/tournament/series.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_launcher,node_app,node_screens,node_controller,node_board,node_renderer,node_themes toneBlue
class node_matchrunner,node_players,node_state,node_types toneAmber
class node_registry,node_basebot,node_regression,node_genetic,node_mcts,node_random toneMint
class node_records,node_history,node_ranking,node_series toneRose
class node_dqn,node_dqnlearn,node_person toneIndigo
```

## Components

### Desktop interface

- [Application launch](https://github.com/august0362/btl_ai/blob/main/main.py): `main.py`
- [Screen manager](https://github.com/august0362/btl_ai/blob/main/frontend/gui/app.py): `frontend/gui/app.py`
- [Game and menu screens](https://github.com/august0362/btl_ai/tree/main/frontend/gui/screens): `frontend/gui/screens`
- [Game controller](https://github.com/august0362/btl_ai/blob/main/frontend/gui/controller.py): `frontend/gui/controller.py`
- [Board view](https://github.com/august0362/btl_ai/blob/main/frontend/gui/widgets/board_view.py): `frontend/gui/widgets/board_view.py`
- [GUI renderer](https://github.com/august0362/btl_ai/blob/main/frontend/gui/render.py): `frontend/gui/render.py`
- [Themes and styling](https://github.com/august0362/btl_ai/blob/main/frontend/gui/theme.py): `frontend/gui/theme.py`

### Match runtime

- [Match runner](https://github.com/august0362/btl_ai/blob/main/backend/tournament/match_runner.py): `backend/tournament/match_runner.py`
- [Player interface](https://github.com/august0362/btl_ai/blob/main/backend/tournament/players.py): `backend/tournament/players.py`
- [Chess game state](https://github.com/august0362/btl_ai/blob/main/backend/core/game_state.py): `backend/core/game_state.py`
- [Game and move types](https://github.com/august0362/btl_ai/blob/main/backend/core/types.py): `backend/core/types.py`

### AI players

- [Bot registry](https://github.com/august0362/btl_ai/blob/main/backend/ai/registry.py): `backend/ai/registry.py`
- [Bot interface](https://github.com/august0362/btl_ai/blob/main/backend/ai/base_bot.py): `backend/ai/base_bot.py`
- [Regression alpha-beta](https://github.com/august0362/btl_ai/blob/main/backend/ai/alphabeta_regression/bot.py): `backend/ai/alphabeta_regression/bot.py`
- [Genetic alpha-beta](https://github.com/august0362/btl_ai/tree/main/backend/ai/genetic_alphabeta): `backend/ai/genetic_alphabeta`
- [Pure MCTS](https://github.com/august0362/btl_ai/blob/main/backend/ai/mcts/bot.py): `backend/ai/mcts/bot.py`
- [Random bot](https://github.com/august0362/btl_ai/blob/main/backend/ai/random_bot/bot.py): `backend/ai/random_bot/bot.py`

### Records and rankings

- [Game records](https://github.com/august0362/btl_ai/blob/main/backend/tournament/records.py): `backend/tournament/records.py`
- [Game history](https://github.com/august0362/btl_ai/blob/main/backend/tournament/history.py): `backend/tournament/history.py`
- [Elo ranking](https://github.com/august0362/btl_ai/blob/main/backend/tournament/ranking.py): `backend/tournament/ranking.py`
- [Match series](https://github.com/august0362/btl_ai/blob/main/backend/tournament/series.py): `backend/tournament/series.py`

### DQN learning

- [Deep RL bot](https://github.com/august0362/btl_ai/blob/main/backend/ai/deep_rl/bot.py): `backend/ai/deep_rl/bot.py`
- [DQN training and evaluation](https://github.com/august0362/btl_ai/tree/main/backend/ai/deep_rl/user): `backend/ai/deep_rl/user`

### Other components

- **Player**

## Connections

- Player → Game and menu screens: chooses moves (evidence: `frontend/gui/screens/game.py`)
- Application launch → Screen manager: launches (evidence: `main.py`)
- Screen manager → Game and menu screens: routes screens (evidence: `frontend/gui/app.py`)
- Game and menu screens → Game controller: reads snapshots (evidence: `frontend/gui/screens/game.py`)
- Game and menu screens → Board view: uses board view (evidence: `frontend/gui/screens/game.py`)
- Board view → GUI renderer: draws through (evidence: `frontend/gui/widgets/board_view.py`)
- GUI renderer → Themes and styling: uses theme (evidence: `frontend/gui/widgets/button.py`)
- Screen manager → Game controller: creates controller (evidence: `frontend/gui/app.py`)
- Game controller → Match runner: runs matches (evidence: `frontend/gui/controller.py`)
- Game controller → Player interface: wraps players (evidence: `frontend/gui/controller.py`)
- Match runner → Player interface: requests moves (evidence: `backend/tournament/match_runner.py`)
- Match runner → Chess game state: updates game (evidence: `backend/tournament/match_runner.py`)
- Match runner → Game records: builds record (evidence: `backend/tournament/match_runner.py`)
- Chess game state → Game and move types: uses game types (evidence: `backend/core/game_state.py`)
- Game records → Game and move types: stores result types (evidence: `backend/tournament/records.py`)
- Screen manager → Bot registry: lists bots (evidence: `frontend/gui/app.py`)
- Bot registry → Bot interface: uses bot interface (evidence: `backend/ai/registry.py`)
- Regression alpha-beta → Bot interface: implements interface (evidence: `backend/ai/alphabeta_regression/bot.py`)
- Genetic alpha-beta → Bot interface: implements interface
- Pure MCTS → Bot interface: implements interface (evidence: `backend/ai/mcts/bot.py`)
- Random bot → Bot interface: implements interface (evidence: `backend/ai/random_bot/bot.py`)
- Deep RL bot → Bot interface: implements interface
- DQN training and evaluation → Deep RL bot: trains policy
- Game controller → Game history: supplies history (evidence: `frontend/gui/controller.py`)
- Game controller → Elo ranking: supplies ranking (evidence: `frontend/gui/controller.py`)
- Game history → Game records: loads records (evidence: `backend/tournament/history.py`)
- Elo ranking → Game records: rates results (evidence: `backend/tournament/ranking.py`)
- Match series → Match runner: runs games (evidence: `backend/tournament/series.py`)
- Match series → Player interface: uses players (evidence: `backend/tournament/series.py`)
- Match series → Game records: collects records (evidence: `backend/tournament/series.py`)
- Screen manager → Game history: loads replay (evidence: `frontend/gui/app.py`)
- Screen manager → Elo ranking: creates ranking (evidence: `frontend/gui/app.py`)
