# gamcrosskf/chess architecture

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

- Interactive diagram: https://gitdiagram.com/gamcrosskf/chess
- Repository: https://github.com/gamcrosskf/chess

## Overview

1. **Project shape**
   This is a Python chess application organized around a central game/controller layer, a reusable AI engine layer, and a heuristic/evaluation layer. The repository is not a service/backend; it is a desktop game with Tkinter UI and a chess rules library underneath.

2. **Entry points**
   `main.py` is the primary launcher. `main_archive.py` and `starter-chess.py` appear to be alternative or legacy startup scripts, but `main.py` is the main integration point that wires players, engines, heuristics, and the game loop together.

3. **Core orchestration: `ChessGame`**
   `ChessGame.py` is the hub of the application. It owns the game session configuration, turn flow, board rendering, optional board flipping, starting position/FEN initialization, and optional output/save behavior. It coordinates between human input, AI decision-making, and the underlying chess rules engine.

4. **Rules and board state**
   The README indicates `python-chess` is the foundation for legal move generation and rule enforcement. That means the project’s own code focuses on orchestration, UI, and AI, while `python-chess` provides the authoritative board state, move legality, FEN handling, and game-state logic.

5. **Player abstraction**
   `ChessPlayer.py` likely represents one side of a match and abstracts whether that side is human or AI-driven. In practice, the game layer uses this abstraction to ask either for user input or for an engine-selected move, without hard-coding the source of the move.

6. **AI engine layer**
   The `ChessEngine/` package contains three search strategies:
   - `ChessEngineMinMax.py` for baseline minimax
   - `ChessEngineMinMaxAlphaBeta.py` for minimax with alpha-beta pruning
   - `ChessEngineAlphaBetaThreaded.py` for a threaded alpha-beta variant  
   `ChessEngine.py` is the base abstraction. This layer consumes board positions and returns candidate moves, typically at a configured search depth.

7. **Heuristic/evaluation layer**
   The `ChessHeuristic/` package separates move search from board evaluation. `ChessHeuristic.py` is the base class, and `ChessHeuristic_AP_CC.py` is the concrete custom heuristic. The engines call this heuristic at leaf nodes or evaluation points to score positions, so the quality of play depends heavily on this subsystem.

8. **Primary data flow**
   The main loop is: game state from `ChessGame` → current board position passed to the current player → if AI, engine searches using heuristic and depth → chosen move returned to `ChessGame` → move applied through `python-chess` → UI refresh and optional save/output. Human-vs-human, human-vs-AI, and AI-vs-AI are just different configurations of the same flow.

9. **User interface and rendering**
   The UI is Tkinter-based, and piece artwork lives in `chessPieces/` as PNG assets. This means the visual layer is mostly local/static: the controller renders board state using these images, rather than using any external frontend or service.

10. **Configuration boundaries**
   Game behavior is configured at construction time through `ChessGame` parameters such as `UI`, `render`, `flip`, `starting_position`, `output`, and `no_save`. This makes the game session itself the main boundary object: once configured, it encapsulates both play mode and presentation mode.

11. **Concurrency boundary**
   Threading is isolated to `ChessEngineAlphaBetaThreaded`. That suggests parallel search is a performance optimization inside one engine implementation, not a system-wide concurrency model. The rest of the application appears to remain single-session, single-board, and UI-driven.

12. **What to draw in an architecture diagram**
   The most important boxes are: `main.py` as bootstrap, `ChessGame` as coordinator, `ChessPlayer` as participant abstraction, `ChessEngine` implementations as AI decision services, `ChessHeuristic` as evaluation service, `python-chess` as rules/state engine, and `chessPieces` plus Tkinter as presentation assets. The clearest arrows are from game state to engine/heuristic and back from engine-selected move into the game loop.

Main entry points: [`ChessGame.py`](https://github.com/gamcrosskf/chess/blob/main/ChessGame.py) (ChessGame), [`ChessEngine/ChessEngine.py`](https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngine.py) (Engine base), [`ChessHeuristic/ChessHeuristic.py`](https://github.com/gamcrosskf/chess/blob/main/ChessHeuristic/ChessHeuristic.py) (Heuristic base), [`ChessPlayer.py`](https://github.com/gamcrosskf/chess/blob/main/ChessPlayer.py) (ChessPlayer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core game"]
  node_chess_game["ChessGame<br/>session coordinator<br/>[ChessGame.py]"]
  node_chess_player["ChessPlayer<br/>player abstraction<br/>[ChessPlayer.py]"]
  node_python_chess[("python-chess<br/>rules engine")]
end

subgraph group_ai["AI layer"]
  node_engine_base["Engine base<br/>engine interface<br/>[ChessEngine.py]"]
  node_engine_minmax["Minimax<br/>search engine"]
  node_engine_alphabeta["Alpha-beta<br/>search engine"]
  node_engine_threaded["Threaded AB<br/>search engine"]
  node_heuristic_base["Heuristic base<br/>evaluation interface<br/>[ChessHeuristic.py]"]
  node_heuristic_cc["AP_CC<br/>custom heuristic"]
end

subgraph group_ui["Presentation"]
  node_tkinter_ui["Tkinter UI<br/>desktop UI"]
  node_piece_assets["Pieces<br/>image assets"]
end

subgraph group_entry["Entry points"]
  node_main["main.py<br/>launcher<br/>[main.py]"]
  node_main_archive["archive<br/>legacy launcher<br/>[main_archive.py]"]
  node_starter_chess["starter<br/>legacy launcher<br/>[starter-chess.py]"]
end

node_readme["README<br/>docs<br/>[README.md]"]

node_main -->|"starts"| node_chess_game
node_main_archive -.->|"launches"| node_chess_game
node_starter_chess -.->|"launches"| node_chess_game
node_chess_game -->|"uses"| node_chess_player
node_chess_game -->|"applies moves"| node_python_chess
node_chess_game -->|"renders"| node_tkinter_ui
node_tkinter_ui -->|"loads"| node_piece_assets
node_chess_player -->|"delegates AI"| node_engine_base
node_engine_base -->|"implemented by"| node_engine_minmax
node_engine_base -->|"implemented by"| node_engine_alphabeta
node_engine_base -->|"implemented by"| node_engine_threaded
node_engine_minmax -->|"scores with"| node_heuristic_base
node_engine_alphabeta -->|"scores with"| node_heuristic_base
node_engine_threaded -->|"scores with"| node_heuristic_base
node_heuristic_base -->|"implemented by"| node_heuristic_cc
node_chess_game -.->|"documents"| node_readme

click node_main "https://github.com/gamcrosskf/chess/blob/main/main.py"
click node_main_archive "https://github.com/gamcrosskf/chess/blob/main/main_archive.py"
click node_starter_chess "https://github.com/gamcrosskf/chess/blob/main/starter-chess.py"
click node_chess_game "https://github.com/gamcrosskf/chess/blob/main/ChessGame.py"
click node_chess_player "https://github.com/gamcrosskf/chess/blob/main/ChessPlayer.py"
click node_engine_base "https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngine.py"
click node_engine_minmax "https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineMinMax.py"
click node_engine_alphabeta "https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineMinMaxAlphaBeta.py"
click node_engine_threaded "https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineAlphaBetaThreaded.py"
click node_heuristic_base "https://github.com/gamcrosskf/chess/blob/main/ChessHeuristic/ChessHeuristic.py"
click node_heuristic_cc "https://github.com/gamcrosskf/chess/blob/main/ChessHeuristic/ChessHeuristic_AP_CC.py"
click node_piece_assets "https://github.com/gamcrosskf/chess/tree/main/chessPieces"
click node_readme "https://github.com/gamcrosskf/chess/blob/main/README.md"

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_chess_game,node_chess_player,node_python_chess toneBlue
class node_engine_base,node_engine_minmax,node_engine_alphabeta,node_engine_threaded,node_heuristic_base,node_heuristic_cc toneAmber
class node_tkinter_ui,node_piece_assets toneMint
class node_main,node_main_archive,node_starter_chess toneRose
class node_readme toneNeutral
```

## Components

### Core game

Session orchestration, player abstraction, and rules/state management.

- [ChessGame](https://github.com/gamcrosskf/chess/blob/main/ChessGame.py): session coordinator · Owns configuration, turn flow, rendering, board setup, and move application. · `ChessGame.py`
- [ChessPlayer](https://github.com/gamcrosskf/chess/blob/main/ChessPlayer.py): player abstraction · Represents a side of the match and abstracts human or AI move sources. · `ChessPlayer.py`
- **python-chess**: rules engine · External library providing legal moves, board state, FEN handling, and game rules.

### AI layer

Search strategies and evaluation used for computer play.

- [Engine base](https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngine.py): engine interface · Shared AI engine abstraction used by the search implementations. · `ChessEngine/ChessEngine.py`
- [Minimax](https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineMinMax.py): search engine · Baseline minimax search implementation. · `ChessEngine/ChessEngineMinMax.py`
- [Alpha-beta](https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineMinMaxAlphaBeta.py): search engine · Minimax with alpha-beta pruning. · `ChessEngine/ChessEngineMinMaxAlphaBeta.py`
- [Threaded AB](https://github.com/gamcrosskf/chess/blob/main/ChessEngine/ChessEngineAlphaBetaThreaded.py): search engine · Threaded alpha-beta variant for performance-oriented search. · `ChessEngine/ChessEngineAlphaBetaThreaded.py`
- [Heuristic base](https://github.com/gamcrosskf/chess/blob/main/ChessHeuristic/ChessHeuristic.py): evaluation interface · Shared evaluation abstraction consumed by the search engines. · `ChessHeuristic/ChessHeuristic.py`
- [AP_CC](https://github.com/gamcrosskf/chess/blob/main/ChessHeuristic/ChessHeuristic_AP_CC.py): custom heuristic · Concrete board scoring heuristic used at leaf nodes and evaluation points. · `ChessHeuristic/ChessHeuristic_AP_CC.py`

### Presentation

Tkinter UI and chess piece artwork.

- **Tkinter UI**: desktop UI · Local user interface used to render and interact with the board.
- [Pieces](https://github.com/gamcrosskf/chess/tree/main/chessPieces): image assets · PNG artwork for chess pieces used by the renderer. · `chessPieces`

### Entry points

Launch scripts and alternate startup paths.

- [main.py](https://github.com/gamcrosskf/chess/blob/main/main.py): launcher · Primary application entry point and wiring for a chess session. · `main.py`
- [archive](https://github.com/gamcrosskf/chess/blob/main/main_archive.py): legacy launcher · Alternative or archived startup script. · `main_archive.py`
- [starter](https://github.com/gamcrosskf/chess/blob/main/starter-chess.py): legacy launcher · Additional startup script for launching the game. · `starter-chess.py`

### Other components

- [README](https://github.com/gamcrosskf/chess/blob/main/README.md): docs · Repository overview and usage notes. · `README.md`

## Connections

- main.py → ChessGame: starts · Bootstrap creates and configures the game session.
- archive → ChessGame: launches · Legacy launcher path into the same session coordinator.
- starter → ChessGame: launches · Alternate startup script into the game coordinator.
- ChessGame → ChessPlayer: uses · Game loop asks each side for a move source.
- ChessGame → python-chess: applies moves · Board state and legality are delegated to the rules library.
- ChessGame → Tkinter UI: renders · Session updates the desktop board view.
- Tkinter UI → Pieces: loads · Renderer uses local chess piece images.
- ChessPlayer → Engine base: delegates AI · AI-controlled players call into an engine implementation.
- Engine base → Minimax: implemented by · Baseline search strategy.
- Engine base → Alpha-beta: implemented by · Pruned search strategy.
- Engine base → Threaded AB: implemented by · Threaded search strategy.
- Minimax → Heuristic base: scores with · Search evaluates leaf positions through heuristics.
- Alpha-beta → Heuristic base: scores with · Search evaluates leaf positions through heuristics.
- Threaded AB → Heuristic base: scores with · Threaded search evaluates leaf positions through heuristics.
- Heuristic base → AP_CC: implemented by · Concrete custom evaluation logic.
- ChessGame → README: documents · Usage and architecture are described in the repository README.