# momgui/dots-and-boxes-ai architecture

> Architecture diagram of the GitHub repository momgui/dots-and-boxes-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/momgui/dots-and-boxes-ai
- Repository: https://github.com/momgui/dots-and-boxes-ai

## Overview

This repository provides two Dots and Boxes agents; the game engine and tournament infrastructure are external. The main workflow is that the engine supplies a board and player, an agent searches for a move within its time budget, and returns an action. The Alpha-Beta agent combines iterative deepening, PVS, domain move ordering, and a chain/loop heuristic with Zobrist hashing and a transposition table. The alternative runs independent MCTS trees and merges root statistics. Some orchestration details are documented in the README but absent from the sampled excerpts.

Main entry points: [`src/alphabeta/AlphaBetaTTStrategy.java`](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/AlphaBetaTTStrategy.java) (Alpha-Beta Search), [`src/mcts/ParallelMCTSStrategy.java`](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java) (MCTS Strategy), [`src/alphabeta/transpositionv2.java`](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/transpositionv2.java) (Transposition Table), [`src/alphabeta/heuristicv2.java`](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/heuristicv2.java) (Position Heuristic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_alphabeta["Alpha-Beta Agent"]
  node_ab_strategy["Alpha-Beta Search"]
  node_heuristic["Position Heuristic<br/>[heuristicv2.java]"]
  node_timeout["Search Timeout"]
end

subgraph group_tt["Transposition Support"]
  node_zobrist["Zobrist Hashing<br/>[ZobristHash.java]"]
  node_transposition[("Transposition Table")]
  node_tt_entry["Table Entry<br/>[TTEntry.java]"]
end

subgraph group_mcts["Parallel MCTS Agent"]
  node_mcts_strategy["MCTS Strategy"]
  node_mcts_search["Tree Search"]
  node_mcts_rollout["Rollout Simulation"]
  node_mcts_merge["Root Statistics Merge"]
end

node_tournament(("Tournament Caller"))
node_engine["Game Engine"]

node_tournament -->|"runs match"| node_engine
node_engine -->|"requests move"| node_ab_strategy
node_ab_strategy -->|"returns action"| node_engine
node_ab_strategy -->|"computes position hash"| node_zobrist
node_ab_strategy -->|"looks up and stores"| node_transposition
node_transposition -->|"creates entries"| node_tt_entry
node_ab_strategy -->|"evaluates leaves"| node_heuristic
node_ab_strategy -->|"throws on deadline"| node_timeout
node_engine -->|"requests move"| node_mcts_strategy
node_mcts_strategy -->|"runs parallel trees"| node_mcts_search
node_mcts_search -->|"simulates positions"| node_mcts_rollout
node_mcts_strategy -->|"merges root statistics"| node_mcts_merge
node_mcts_strategy -->|"returns action"| node_engine

click node_ab_strategy "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/AlphaBetaTTStrategy.java"
click node_heuristic "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/heuristicv2.java"
click node_timeout "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/TimeOutException.java"
click node_zobrist "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/ZobristHash.java"
click node_transposition "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/transpositionv2.java"
click node_tt_entry "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/TTEntry.java"
click node_mcts_strategy "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java"
click node_mcts_search "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java"
click node_mcts_rollout "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java"
click node_mcts_merge "https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java"

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_ab_strategy,node_heuristic,node_timeout toneBlue
class node_zobrist,node_transposition,node_tt_entry toneAmber
class node_mcts_strategy,node_mcts_search,node_mcts_rollout,node_mcts_merge toneMint
class node_tournament,node_engine toneIndigo
```

## Components

### Alpha-Beta Agent

- [Alpha-Beta Search](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/AlphaBetaTTStrategy.java): `src/alphabeta/AlphaBetaTTStrategy.java`
- [Position Heuristic](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/heuristicv2.java): `src/alphabeta/heuristicv2.java`
- [Search Timeout](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/TimeOutException.java): `src/alphabeta/TimeOutException.java`

### Transposition Support

- [Zobrist Hashing](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/ZobristHash.java): `src/alphabeta/ZobristHash.java`
- [Transposition Table](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/transpositionv2.java): `src/alphabeta/transpositionv2.java`
- [Table Entry](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/alphabeta/TTEntry.java): `src/alphabeta/TTEntry.java`

### Parallel MCTS Agent

- [MCTS Strategy](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java): `src/mcts/ParallelMCTSStrategy.java`
- [Tree Search](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java): `src/mcts/ParallelMCTSStrategy.java`
- [Rollout Simulation](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java): `src/mcts/ParallelMCTSStrategy.java`
- [Root Statistics Merge](https://github.com/momgui/dots-and-boxes-ai/blob/main/src/mcts/ParallelMCTSStrategy.java): `src/mcts/ParallelMCTSStrategy.java`

### Other components

- **Tournament Caller**
- **Game Engine**

## Connections

- Tournament Caller → Game Engine: runs match (evidence: `README.md`)
- Game Engine → Alpha-Beta Search: requests move (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Alpha-Beta Search → Game Engine: returns action (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Alpha-Beta Search → Zobrist Hashing: computes position hash (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Alpha-Beta Search → Transposition Table: looks up and stores (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Transposition Table → Table Entry: creates entries (evidence: `src/alphabeta/transpositionv2.java`)
- Alpha-Beta Search → Position Heuristic: evaluates leaves (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Alpha-Beta Search → Search Timeout: throws on deadline (evidence: `src/alphabeta/AlphaBetaTTStrategy.java`)
- Game Engine → MCTS Strategy: requests move (evidence: `src/mcts/ParallelMCTSStrategy.java`)
- MCTS Strategy → Tree Search: runs parallel trees (evidence: `src/mcts/ParallelMCTSStrategy.java`)
- Tree Search → Rollout Simulation: simulates positions (evidence: `src/mcts/ParallelMCTSStrategy.java`)
- MCTS Strategy → Root Statistics Merge: merges root statistics (evidence: `src/mcts/ParallelMCTSStrategy.java`)
- MCTS Strategy → Game Engine: returns action (evidence: `src/mcts/ParallelMCTSStrategy.java`)
