# utkarsh-naman/unc architecture

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

- Interactive diagram: https://gitdiagram.com/utkarsh-naman/unc
- Repository: https://github.com/utkarsh-naman/unc

## Overview

1. **Repository purpose and overall shape**  
   This repo packages a “solved” Chopsticks bot around a precomputed game graph. The architecture is not a typical on-demand search engine; it is a pipeline that builds the full state graph offline, annotates it with values, then ships a runtime engine that reads the finalized graph and plays from it.

2. **Core domain model**  
   The game logic is centered on compact state representations for the two players’ hand counts and whose turn it is. The `include/rules.hpp`, `include/utils/state_repr.hpp`, and corresponding `src/utils/state_repr.cpp` files define the canonical representation used throughout the solver, builder, serializer, and runtime engine.

3. **Move-generation subsystem**  
   Legal game transitions are implemented as a set of focused move modules under `include/utils/moves` and `src/utils/moves`. These cover attack variations and redistribution behavior, with helpers such as `arrange_*`, `left_to_*`, `right_to_*`, `distribute`, and `next_state`. This subsystem is the forward edge generator for the game graph.

4. **Reverse-transition / parent discovery subsystem**  
   A parallel set of modules under `include/utils/unmove` and `src/utils/unmove` computes predecessor states. This is important because the solver is built bottom-up: instead of exploring forward from the start state, it propagates values backward from terminal positions through parent links.

5. **Offline map builder pipeline**  
   The `src/MapBuilder` and `build/` directories contain the graph-construction utilities for initial maps such as `map_0` and `map_p_0`. These builders create the raw state graph and the parent map artifacts that later stages consume. The presence of `test_map0`, `test_map_p_0`, and related binaries shows this stage is independently validated.

6. **Value-setting / solving pipeline**  
   `src/MapValueSetter` is where the graph gets solved. The files `set_terminal_depth.cpp`, `set_suicides.cpp`, and `set_score.cpp` indicate a staged annotation process: first mark terminal depths, then assign special values for suicide/terminal conditions, then propagate scores across the graph. The repository’s README calls this the “MaxiMax” approach, but architecturally it is a backward propagation of game values over the precomputed graph.

7. **Final solved map artifact**  
   The culmination of the offline pipeline is `map_final` plus supporting serialized files in `bin/output/map/...`. This final dataset is what the runtime consumes. The architecture depends on this artifact being complete and consistent; the bot’s runtime behavior is driven by lookup and evaluation against this precomputed map, not by running a deep search at play time.

8. **Runtime engine boundary**  
   `src/UncEngine` and `WASM/engine_unc.cpp` contain the play-time engine. This layer loads the final map, evaluates the current game state, and selects a move. It is deliberately separated from the map-building code so the deployed bot stays lightweight and deterministic.

9. **Serialization boundary**  
   `serializer.cpp/.hpp`, `p_serializer.cpp`, and `state_repr.cpp/.hpp` implement the file format and in-memory encoding used to move graph data between builder, solver, and engine. This is the key boundary between the algorithmic graph pipeline and the runtime consumer, and it is also what enables the preloaded `.data` file in the browser build.

10. **WASM / browser packaging**  
   The `WASM` directory contains the browser-facing build: `bindings.cpp` exposes the C++ engine to JavaScript via Emscripten, `index.html` is the demo shell, and `server.py` supports local serving. The generated `chopsticks_bot.js`, `chopsticks_bot.wasm`, and `chopsticks_bot.data` are the deployable artifacts; `cdn` and `cdn4` hold copies for publishing.

11. **Testing and verification**  
   The `tests` directory contains concept checks, reference implementations, parent-map validation, and bot tests. These are important because the solution depends on graph correctness rather than heuristic quality; the tests verify that generated parent relationships and solved values match expected behavior.

12. **Build system and artifact layout**  
   The root `CMakeLists.txt` and the various `*.txt` command lists in `src/MapBuilder`, `src/MapValueSetter`, and `WASM` reflect a multi-stage build process rather than a single compile step. The repo contains both source and generated binaries/data, which signals that the architecture is a toolchain plus runtime, not just a library.

Main entry points: [`src/MapBuilder`](https://github.com/utkarsh-naman/unc/tree/main/src/MapBuilder) (Graph builder), [`src/MapValueSetter`](https://github.com/utkarsh-naman/unc/tree/main/src/MapValueSetter) (Value setter), [`include/utils/state_repr.hpp`](https://github.com/utkarsh-naman/unc/blob/main/include/utils/state_repr.hpp) (State repr), [`src/UncEngine`](https://github.com/utkarsh-naman/unc/tree/main/src/UncEngine) (Unc engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Game model"]
  node_n1["Rules<br/>[rules.hpp]"]
  node_n2["State repr<br/>state encoding<br/>[state_repr.hpp]"]
end

subgraph group_g2["Transition logic"]
  node_n3["Moves<br/>forward transitions"]
  node_n4["Unmoves<br/>reverse transitions"]
end

subgraph group_g3["Offline pipeline"]
  node_n5["Graph builder<br/>map builder"]
  node_n6["Value setter<br/>solver pass"]
  node_n7[("Raw map<br/>unvalued artifact")]
  node_n8[("Parent map<br/>predecessor artifact")]
  node_n9[("Depth map<br/>annotated artifact")]
  node_n10[("Final map<br/>solved artifact")]
end

subgraph group_g4["Runtime"]
  node_n11["Unc engine<br/>runtime engine"]
end

subgraph group_g5["Packaging"]
  node_n12["Serializer<br/>binary format<br/>[serializer.hpp]"]
  node_n13["P serializer<br/>parent-map format<br/>[p_serializer.hpp]"]
  node_n14["WASM engine<br/>browser build<br/>[bindings.cpp]"]
  node_n15[("WASM assets<br/>deployable bundle")]
end

subgraph group_g6["Verification"]
  node_n16["Map tests<br/>validation"]
  node_n17["Build entry<br/>toolchain<br/>[CMakeLists.txt]"]
end

node_n1 -->|"defines"| node_n2
node_n2 -->|"drives"| node_n3
node_n2 -->|"drives"| node_n4
node_n3 -->|"builds"| node_n5
node_n4 -->|"builds"| node_n5
node_n5 -->|"writes"| node_n7
node_n5 -->|"writes"| node_n8
node_n7 -->|"inputs"| node_n6
node_n8 -->|"inputs"| node_n6
node_n6 -->|"produces"| node_n9
node_n9 -->|"produces"| node_n10
node_n10 -->|"loads"| node_n11
node_n2 -->|"serialized by"| node_n12
node_n8 -->|"serialized by"| node_n13
node_n12 -->|"feeds"| node_n11
node_n11 -->|"wrapped by"| node_n14
node_n14 -->|"bundles"| node_n15
node_n17 -->|"orchestrates"| node_n5
node_n17 -->|"orchestrates"| node_n6
node_n17 -->|"orchestrates"| node_n14
node_n16 -->|"validates"| node_n5
node_n16 -->|"validates"| node_n6
node_n16 -->|"validates"| node_n11

click node_n1 "https://github.com/utkarsh-naman/unc/blob/main/include/rules.hpp"
click node_n2 "https://github.com/utkarsh-naman/unc/blob/main/include/utils/state_repr.hpp"
click node_n3 "https://github.com/utkarsh-naman/unc/tree/main/include/utils/moves"
click node_n4 "https://github.com/utkarsh-naman/unc/tree/main/include/utils/unmove"
click node_n5 "https://github.com/utkarsh-naman/unc/tree/main/src/MapBuilder"
click node_n6 "https://github.com/utkarsh-naman/unc/tree/main/src/MapValueSetter"
click node_n7 "https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/unvalued/map_0"
click node_n8 "https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/unvalued/map_p_0"
click node_n9 "https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/valued/map_1_depth"
click node_n10 "https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/valued/map_final"
click node_n11 "https://github.com/utkarsh-naman/unc/tree/main/src/UncEngine"
click node_n12 "https://github.com/utkarsh-naman/unc/blob/main/include/utils/serializer.hpp"
click node_n13 "https://github.com/utkarsh-naman/unc/blob/main/include/utils/p_serializer.hpp"
click node_n14 "https://github.com/utkarsh-naman/unc/blob/main/WASM/bindings.cpp"
click node_n15 "https://github.com/utkarsh-naman/unc/blob/main/WASM/chopsticks_bot.data"
click node_n16 "https://github.com/utkarsh-naman/unc/tree/main/tests"
click node_n17 "https://github.com/utkarsh-naman/unc/blob/main/CMakeLists.txt"

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_n1,node_n2 toneBlue
class node_n3,node_n4 toneAmber
class node_n5,node_n6,node_n7,node_n8,node_n9,node_n10 toneMint
class node_n11 toneRose
class node_n12,node_n13,node_n14,node_n15 toneIndigo
class node_n16,node_n17 toneTeal
```

## Components

### Game model

Canonical Chopsticks state representation and rule helpers.

- [Rules](https://github.com/utkarsh-naman/unc/blob/main/include/rules.hpp): game rules · Core game constraints and turn semantics. · `include/rules.hpp`
- [State repr](https://github.com/utkarsh-naman/unc/blob/main/include/utils/state_repr.hpp): state encoding · Compact canonical state encoding shared across the solver and engine. · `include/utils/state_repr.hpp`

### Transition logic

Forward move generation and reverse predecessor discovery used by the solver.

- [Moves](https://github.com/utkarsh-naman/unc/tree/main/include/utils/moves): forward transitions · Legal state transitions for attacks and redistribution. · `include/utils/moves`
- [Unmoves](https://github.com/utkarsh-naman/unc/tree/main/include/utils/unmove): reverse transitions · Predecessor-state logic for backward propagation over the graph. · `include/utils/unmove`

### Offline pipeline

Build stages that construct the state graph, derive parent maps, and annotate values.

- [Graph builder](https://github.com/utkarsh-naman/unc/tree/main/src/MapBuilder): map builder · Offline construction of raw state graphs and parent maps. · `src/MapBuilder`
- [Value setter](https://github.com/utkarsh-naman/unc/tree/main/src/MapValueSetter): solver pass · Staged annotation pipeline for terminal depth, suicides, and scores. · `src/MapValueSetter`
- [Raw map](https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/unvalued/map_0): unvalued artifact · Precomputed graph before value propagation. · `bin/output/map/unvalued/map_0`
- [Parent map](https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/unvalued/map_p_0): predecessor artifact · Graph artifact containing reverse links for solving. · `bin/output/map/unvalued/map_p_0`
- [Depth map](https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/valued/map_1_depth): annotated artifact · Intermediate valued map after terminal-depth propagation. · `bin/output/map/valued/map_1_depth`
- [Final map](https://github.com/utkarsh-naman/unc/tree/main/bin/output/map/valued/map_final): solved artifact · Completed solved dataset consumed by the runtime engine. · `bin/output/map/valued/map_final`

### Runtime

Play-time engine that loads the finalized map and selects moves.

- [Unc engine](https://github.com/utkarsh-naman/unc/tree/main/src/UncEngine): runtime engine · Play-time engine that loads the final map and chooses moves. · `src/UncEngine`

### Packaging

Serialization and browser deployment boundary for precomputed artifacts.

- [Serializer](https://github.com/utkarsh-naman/unc/blob/main/include/utils/serializer.hpp): binary format · Read/write boundary for map and state data. · `include/utils/serializer.hpp`
- [P serializer](https://github.com/utkarsh-naman/unc/blob/main/include/utils/p_serializer.hpp): parent-map format · Specialized serialization for parent-map artifacts. · `include/utils/p_serializer.hpp`
- [WASM engine](https://github.com/utkarsh-naman/unc/blob/main/WASM/bindings.cpp): browser build · Emscripten-exposed engine and browser-facing wrapper. · `WASM/bindings.cpp`
- [WASM assets](https://github.com/utkarsh-naman/unc/blob/main/WASM/chopsticks_bot.data): deployable bundle · Generated JS, WASM, and data payload used by the browser demo. · `WASM/chopsticks_bot.data`

### Verification

Checks that validate generated maps, parents, and runtime behavior.

- [Map tests](https://github.com/utkarsh-naman/unc/tree/main/tests): validation · Checks for map construction, parent correctness, and bot behavior. · `tests`
- [Build entry](https://github.com/utkarsh-naman/unc/blob/main/CMakeLists.txt): toolchain · Top-level CMake build orchestration for sources and generated artifacts. · `CMakeLists.txt`

## Connections

- Rules → State repr: defines · Rules constrain the canonical state representation.
- State repr → Moves: drives · State encoding feeds forward move generation.
- State repr → Unmoves: drives · State encoding also feeds predecessor discovery.
- Moves → Graph builder: builds · Forward transitions populate the offline graph builder.
- Unmoves → Graph builder: builds · Reverse transitions support parent-map construction.
- Graph builder → Raw map: writes · Builder emits the raw unvalued map.
- Graph builder → Parent map: writes · Builder emits the parent map artifact.
- Raw map → Value setter: inputs · Raw graph is the substrate for solving passes.
- Parent map → Value setter: inputs · Parent links guide backward value propagation.
- Value setter → Depth map: produces · Intermediate depth annotation is staged output.
- Depth map → Final map: produces · Final score propagation yields the solved map.
- Final map → Unc engine: loads · Runtime engine consumes the solved dataset.
- State repr → Serializer: serialized by · State representation is persisted through the serializer boundary.
- Parent map → P serializer: serialized by · Parent-map artifacts use a specialized serializer.
- Serializer → Unc engine: feeds · Engine relies on serialized map/state loading.
- Unc engine → WASM engine: wrapped by · Browser build exposes the engine via bindings.
- WASM engine → WASM assets: bundles · Browser packaging produces JS/WASM/data artifacts.
- Build entry → Graph builder: orchestrates · Build system drives map-builder targets.
- Build entry → Value setter: orchestrates · Build system drives value-setter targets.
- Build entry → WASM engine: orchestrates · Build system also drives the WASM target.
- Map tests → Graph builder: validates · Tests check builder output and parent maps.
- Map tests → Value setter: validates · Tests verify solved values and special cases.
- Map tests → Unc engine: validates · Bot tests exercise the runtime engine behavior.