# minuskelvin/cold-clear-2 architecture

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

- Interactive diagram: https://gitdiagram.com/minuskelvin/cold-clear-2
- Repository: https://github.com/minuskelvin/cold-clear-2

## Overview

Cold Clear 2 is a Tetris-versus bot that speaks the Tetris Bot Protocol (TBP) to a frontend. The main workflow receives game events, builds or updates bot state, searches for placements, and returns suggestions; a worker performs ongoing search while the protocol loop handles requests. Search combines move generation, freestyle evaluation, and a transposition-aware DAG with known-piece and speculative layers. The README documents bitboard representation and multithreaded search. Some implementation files were not sampled, so links to internal search components reflect only supported wiring.

Main entry points: [`src/lib.rs`](https://github.com/minuskelvin/cold-clear-2/blob/main/src/lib.rs) (Protocol loop), [`src/sync.rs`](https://github.com/minuskelvin/cold-clear-2/blob/main/src/sync.rs) (Bot synchronizer), [`src/bot.rs`](https://github.com/minuskelvin/cold-clear-2/blob/main/src/bot.rs) (Bot search control), [`src/main.rs`](https://github.com/minuskelvin/cold-clear-2/blob/main/src/main.rs) (Command-line adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["TBP interaction"]
  node_protocol_loop["Protocol loop<br/>[lib.rs]"]
  node_tbp_messages["TBP messages<br/>[tbp.rs]"]
  node_suggestion["Move suggestions<br/>[tbp.rs]"]
  node_cli["Command-line adapter<br/>[main.rs]"]
end

subgraph group_bot["Bot lifecycle"]
  node_sync["Bot synchronizer<br/>[sync.rs]"]
  node_bot_core["Bot search control<br/>[bot.rs]"]
  node_freestyle["Freestyle strategy<br/>[freestyle.rs]"]
  node_config["Bot configuration<br/>[default.json]"]
  node_worker["Search worker<br/>[sync.rs]"]
end

subgraph group_search["Search engine"]
  node_dag["Search DAG<br/>[dag.rs]"]
  node_known_layer["Known-piece layer<br/>[known.rs]"]
  node_speculated_layer["Speculative layer<br/>[speculated.rs]"]
  node_movegen["Move generation<br/>[movegen.rs]"]
  node_state_map[("State map<br/>[map.rs]")]
end

subgraph group_model["Game model"]
  node_game_state["Game state<br/>[data.rs]"]
  node_board["Column bitboard<br/>[data.rs]"]
end

node_frontend(("TBP frontend"))

node_frontend -->|"sends lines"| node_cli
node_cli -->|"decodes JSON"| node_tbp_messages
node_cli -->|"runs"| node_protocol_loop
node_protocol_loop -->|"handles messages"| node_tbp_messages
node_protocol_loop -->|"dispatches events"| node_sync
node_sync -->|"updates and queries"| node_bot_core
node_protocol_loop -->|"creates bot"| node_bot_core
node_protocol_loop -->|"loads defaults"| node_config
node_worker -->|"works through"| node_sync
node_sync -->|"runs search"| node_bot_core
node_bot_core -->|"selects and advances"| node_dag
node_bot_core -->|"uses strategy"| node_freestyle
node_freestyle -->|"generates placements"| node_movegen
node_freestyle -->|"evaluates positions"| node_game_state
node_dag -->|"dispatches"| node_known_layer
node_dag -->|"dispatches"| node_speculated_layer
node_known_layer -->|"indexes states"| node_state_map
node_speculated_layer -->|"indexes states"| node_state_map
node_protocol_loop -->|"constructs initial state"| node_game_state
node_game_state -->|"contains bitboard"| node_board
node_sync -->|"returns suggestion data"| node_suggestion
node_protocol_loop -->|"sends responses"| node_frontend

click node_protocol_loop "https://github.com/minuskelvin/cold-clear-2/blob/main/src/lib.rs"
click node_tbp_messages "https://github.com/minuskelvin/cold-clear-2/blob/main/src/tbp.rs"
click node_suggestion "https://github.com/minuskelvin/cold-clear-2/blob/main/src/tbp.rs"
click node_sync "https://github.com/minuskelvin/cold-clear-2/blob/main/src/sync.rs"
click node_bot_core "https://github.com/minuskelvin/cold-clear-2/blob/main/src/bot.rs"
click node_freestyle "https://github.com/minuskelvin/cold-clear-2/blob/main/src/bot/freestyle.rs"
click node_config "https://github.com/minuskelvin/cold-clear-2/blob/main/src/default.json"
click node_worker "https://github.com/minuskelvin/cold-clear-2/blob/main/src/sync.rs"
click node_dag "https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag.rs"
click node_known_layer "https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag/known.rs"
click node_speculated_layer "https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag/speculated.rs"
click node_movegen "https://github.com/minuskelvin/cold-clear-2/blob/main/src/movegen.rs"
click node_state_map "https://github.com/minuskelvin/cold-clear-2/blob/main/src/map.rs"
click node_game_state "https://github.com/minuskelvin/cold-clear-2/blob/main/src/data.rs"
click node_board "https://github.com/minuskelvin/cold-clear-2/blob/main/src/data.rs"
click node_cli "https://github.com/minuskelvin/cold-clear-2/blob/main/src/main.rs"

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_protocol_loop,node_tbp_messages,node_suggestion,node_cli,node_frontend toneBlue
class node_sync,node_bot_core,node_freestyle,node_config,node_worker toneAmber
class node_dag,node_known_layer,node_speculated_layer,node_movegen,node_state_map toneMint
class node_game_state,node_board toneRose
```

## Components

### TBP interaction

- [Protocol loop](https://github.com/minuskelvin/cold-clear-2/blob/main/src/lib.rs): `src/lib.rs`
- [TBP messages](https://github.com/minuskelvin/cold-clear-2/blob/main/src/tbp.rs): `src/tbp.rs`
- [Move suggestions](https://github.com/minuskelvin/cold-clear-2/blob/main/src/tbp.rs): `src/tbp.rs`
- [Command-line adapter](https://github.com/minuskelvin/cold-clear-2/blob/main/src/main.rs): `src/main.rs`

### Bot lifecycle

- [Bot synchronizer](https://github.com/minuskelvin/cold-clear-2/blob/main/src/sync.rs): `src/sync.rs`
- [Bot search control](https://github.com/minuskelvin/cold-clear-2/blob/main/src/bot.rs): `src/bot.rs`
- [Freestyle strategy](https://github.com/minuskelvin/cold-clear-2/blob/main/src/bot/freestyle.rs): `src/bot/freestyle.rs`
- [Bot configuration](https://github.com/minuskelvin/cold-clear-2/blob/main/src/default.json): `src/default.json`
- [Search worker](https://github.com/minuskelvin/cold-clear-2/blob/main/src/sync.rs): `src/sync.rs`

### Search engine

- [Search DAG](https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag.rs): `src/dag.rs`
- [Known-piece layer](https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag/known.rs): `src/dag/known.rs`
- [Speculative layer](https://github.com/minuskelvin/cold-clear-2/blob/main/src/dag/speculated.rs): `src/dag/speculated.rs`
- [Move generation](https://github.com/minuskelvin/cold-clear-2/blob/main/src/movegen.rs): `src/movegen.rs`
- [State map](https://github.com/minuskelvin/cold-clear-2/blob/main/src/map.rs): `src/map.rs`

### Game model

- [Game state](https://github.com/minuskelvin/cold-clear-2/blob/main/src/data.rs): `src/data.rs`
- [Column bitboard](https://github.com/minuskelvin/cold-clear-2/blob/main/src/data.rs): `src/data.rs`

### Other components

- **TBP frontend**

## Connections

- TBP frontend → Command-line adapter: sends lines
- Command-line adapter → TBP messages: decodes JSON
- Command-line adapter → Protocol loop: runs
- Protocol loop → TBP messages: handles messages
- Protocol loop → Bot synchronizer: dispatches events
- Bot synchronizer → Bot search control: updates and queries
- Protocol loop → Bot search control: creates bot
- Protocol loop → Bot configuration: loads defaults
- Search worker → Bot synchronizer: works through
- Bot synchronizer → Bot search control: runs search
- Bot search control → Search DAG: selects and advances
- Bot search control → Freestyle strategy: uses strategy
- Freestyle strategy → Move generation: generates placements
- Freestyle strategy → Game state: evaluates positions
- Search DAG → Known-piece layer: dispatches
- Search DAG → Speculative layer: dispatches
- Known-piece layer → State map: indexes states
- Speculative layer → State map: indexes states
- Protocol loop → Game state: constructs initial state
- Game state → Column bitboard: contains bitboard
- Bot synchronizer → Move suggestions: returns suggestion data
- Protocol loop → TBP frontend: sends responses