# till75/rlcheckers architecture

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

- Interactive diagram: https://gitdiagram.com/till75/rlcheckers
- Repository: https://github.com/till75/rlcheckers

## Overview

RLCheckers is a reproducible 5×5 checkers reinforcement-learning experiment. Users invoke the CLI to play a seeded random game, evaluate agents, train a Q-table, or run the three-seed gate. Those workflows depend on immutable board, move, and game-state rules; agents provide random, greedy, and Q-table play. Training supports fixed-random-opponent Q-learning and self-play against frozen snapshots, while evaluation runs seeded matchups, computes metrics, and writes artifacts. Edges reflect shown imports, documented behavior, or the CLI excerpt; several implementation details are unsampled, so uncertain wiring is omitted.

Main entry points: [`src/rlcheckers/game/state.py`](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/state.py) (Game state), [`src/rlcheckers/evaluation/gate.py`](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/gate.py) (Three-seed gate), [`src/rlcheckers/cli.py`](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/cli.py) (CLI commands), [`src/rlcheckers/evaluation/arena.py`](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/arena.py) (Match arena)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rules["Game rules"]
  node_board["Board encoding<br/>[board.py]"]
  node_moves["Legal moves<br/>[moves.py]"]
  node_state["Game state<br/>[state.py]"]
end

subgraph group_agents["Playing agents"]
  node_protocol["Agent protocol<br/>[protocol.py]"]
  node_random["Random agent<br/>[random_agent.py]"]
  node_greedy["Greedy agent<br/>[greedy_agent.py]"]
  node_qagent["Q-table agent<br/>[q_agent.py]"]
end

subgraph group_training["Training"]
  node_trainq["Fixed-opponent Q-learning<br/>[train_q.py]"]
  node_selfplay["Snapshot self-play<br/>[self_play.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_arena["Match arena<br/>[arena.py]"]
  node_metrics["Score metrics<br/>[metrics.py]"]
  node_artifacts["Evaluation artifacts<br/>[artifacts.py]"]
  node_gate["Three-seed gate<br/>[gate.py]"]
end

subgraph group_interface["Command interface"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_config["Config validation<br/>[config.py]"]
end

node_user(("Experimenter"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"runs matchups"| node_arena
node_cli -->|"starts training"| node_trainq
node_cli -->|"dispatches self-play"| node_selfplay
node_cli -->|"runs gate"| node_gate
node_board -->|"supplies board"| node_moves
node_board -->|"wrapped by"| node_state
node_moves -->|"applied by"| node_state
node_state -->|"agent input"| node_protocol
node_state -->|"chooses moves from"| node_random
node_state -->|"evaluated by"| node_greedy
node_state -->|"valued by"| node_qagent
node_state -->|"training state"| node_trainq
node_state -->|"training state"| node_selfplay
node_trainq -->|"updates Q-table"| node_qagent
node_selfplay -->|"freezes snapshots"| node_qagent
node_arena -->|"requests moves"| node_protocol
node_arena -->|"plays games"| node_state
node_metrics -->|"summarizes results"| node_arena
node_artifacts -->|"writes matchup data"| node_arena
node_artifacts -->|"writes summaries"| node_metrics
node_gate -->|"trains seeds"| node_selfplay
node_gate -->|"evaluates matchups"| node_arena
node_gate -->|"aggregates scores"| node_metrics
node_gate -->|"tests baseline"| node_greedy
node_gate -->|"tests baseline"| node_random
node_gate -->|"evaluates learned agent"| node_qagent

click node_cli "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/cli.py"
click node_config "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/config.py"
click node_board "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/board.py"
click node_moves "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/moves.py"
click node_state "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/state.py"
click node_protocol "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/protocol.py"
click node_random "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/random_agent.py"
click node_greedy "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/greedy_agent.py"
click node_qagent "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/q_agent.py"
click node_trainq "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/training/train_q.py"
click node_selfplay "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/training/self_play.py"
click node_arena "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/arena.py"
click node_metrics "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/metrics.py"
click node_artifacts "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/artifacts.py"
click node_gate "https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/gate.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_board,node_moves,node_state toneBlue
class node_protocol,node_random,node_greedy,node_qagent toneAmber
class node_trainq,node_selfplay toneMint
class node_arena,node_metrics,node_artifacts,node_gate toneRose
class node_cli,node_config,node_user toneIndigo
```

## Components

### Game rules

- [Board encoding](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/board.py): `src/rlcheckers/game/board.py`
- [Legal moves](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/moves.py): `src/rlcheckers/game/moves.py`
- [Game state](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/game/state.py): `src/rlcheckers/game/state.py`

### Playing agents

- [Agent protocol](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/protocol.py): `src/rlcheckers/agents/protocol.py`
- [Random agent](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/random_agent.py): `src/rlcheckers/agents/random_agent.py`
- [Greedy agent](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/greedy_agent.py): `src/rlcheckers/agents/greedy_agent.py`
- [Q-table agent](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/agents/q_agent.py): `src/rlcheckers/agents/q_agent.py`

### Training

- [Fixed-opponent Q-learning](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/training/train_q.py): `src/rlcheckers/training/train_q.py`
- [Snapshot self-play](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/training/self_play.py): `src/rlcheckers/training/self_play.py`

### Evaluation

- [Match arena](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/arena.py): `src/rlcheckers/evaluation/arena.py`
- [Score metrics](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/metrics.py): `src/rlcheckers/evaluation/metrics.py`
- [Evaluation artifacts](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/artifacts.py): `src/rlcheckers/evaluation/artifacts.py`
- [Three-seed gate](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/evaluation/gate.py): `src/rlcheckers/evaluation/gate.py`

### Command interface

- [CLI commands](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/cli.py): `src/rlcheckers/cli.py`
- [Config validation](https://github.com/till75/rlcheckers/blob/main/src/rlcheckers/config.py): `src/rlcheckers/config.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Config validation: loads settings (evidence: `src/rlcheckers/cli.py`)
- CLI commands → Match arena: runs matchups (evidence: `src/rlcheckers/cli.py`)
- CLI commands → Fixed-opponent Q-learning: starts training (evidence: `src/rlcheckers/cli.py`)
- CLI commands → Snapshot self-play: dispatches self-play (evidence: `src/rlcheckers/cli.py`)
- CLI commands → Three-seed gate: runs gate (evidence: `src/rlcheckers/cli.py`)
- Board encoding → Legal moves: supplies board (evidence: `src/rlcheckers/game/moves.py`)
- Board encoding → Game state: wrapped by (evidence: `src/rlcheckers/game/state.py`)
- Legal moves → Game state: applied by (evidence: `src/rlcheckers/game/state.py`)
- Game state → Agent protocol: agent input (evidence: `src/rlcheckers/agents/protocol.py`)
- Game state → Random agent: chooses moves from (evidence: `src/rlcheckers/agents/random_agent.py`)
- Game state → Greedy agent: evaluated by (evidence: `src/rlcheckers/agents/greedy_agent.py`)
- Game state → Q-table agent: valued by (evidence: `src/rlcheckers/agents/q_agent.py`)
- Game state → Fixed-opponent Q-learning: training state (evidence: `src/rlcheckers/training/train_q.py`)
- Game state → Snapshot self-play: training state (evidence: `src/rlcheckers/training/self_play.py`)
- Fixed-opponent Q-learning → Q-table agent: updates Q-table (evidence: `src/rlcheckers/training/train_q.py`)
- Snapshot self-play → Q-table agent: freezes snapshots (evidence: `src/rlcheckers/training/self_play.py`)
- Match arena → Agent protocol: requests moves (evidence: `src/rlcheckers/evaluation/arena.py`)
- Match arena → Game state: plays games (evidence: `src/rlcheckers/evaluation/arena.py`)
- Score metrics → Match arena: summarizes results (evidence: `src/rlcheckers/evaluation/metrics.py`)
- Evaluation artifacts → Match arena: writes matchup data (evidence: `src/rlcheckers/evaluation/artifacts.py`)
- Evaluation artifacts → Score metrics: writes summaries (evidence: `src/rlcheckers/evaluation/artifacts.py`)
- Three-seed gate → Snapshot self-play: trains seeds (evidence: `src/rlcheckers/evaluation/gate.py`)
- Three-seed gate → Match arena: evaluates matchups (evidence: `src/rlcheckers/evaluation/gate.py`)
- Three-seed gate → Score metrics: aggregates scores (evidence: `src/rlcheckers/evaluation/gate.py`)
- Three-seed gate → Greedy agent: tests baseline (evidence: `src/rlcheckers/evaluation/gate.py`)
- Three-seed gate → Random agent: tests baseline (evidence: `src/rlcheckers/evaluation/gate.py`)
- Three-seed gate → Q-table agent: evaluates learned agent (evidence: `src/rlcheckers/evaluation/gate.py`)