# utkarsh-naman/3t architecture

> Architecture diagram of the GitHub repository utkarsh-naman/3t, 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/3t
- Repository: https://github.com/utkarsh-naman/3t

## Overview

1. **Repository shape**
   - This repo is centered on a tic-tac-toe engine called **3T**, with the main implementation in **Go**.
   - It also contains two packaging/porting tracks:
     - a **Go WebAssembly** build under `WASM/`
     - a **Rust** implementation under `Rust/` and `WASM Rust/`
   - The overall architecture is the same across these tracks: build a compact game graph offline, then run a small engine against that graph at runtime.

2. **Core runtime engine**
   - The runtime engine lives in `src/TTTEngine/`.
   - Its responsibility is to take a board state, look it up in the precomputed game graph, and determine outcomes / next choices.
   - The engine is intentionally lightweight because most expensive reasoning is pushed into offline map construction.

3. **Game-state model layer**
   - `src/model/` defines the data structures for the game graph and node/state representation.
   - This is the shared boundary between the builder and the engine: the builder produces graph data in this model, and the engine consumes it.
   - In the Rust port, the same role is played by `Rust/src/model/` and the mirrored WASM Rust files.

4. **Offline map-building pipeline**
   - `src/mapBuilder/` is the graph generation pipeline.
   - It appears to run in stages:
     - build an empty map / initial structure
     - assign terminal values
     - propagate or finalize values for non-terminal states
   - The build steps are also called out directly in the README, which suggests graph generation is a required preprocessing step before using the engine.

5. **Symmetry reduction as a major optimization**
   - `src/SymmetryReduction/` is a key architectural subsystem.
   - It reduces equivalent tic-tac-toe positions under board symmetries, so the engine stores and evaluates fewer distinct states.
   - This is one of the main reasons the engine is “resource optimized”: many board states collapse to a canonical representative before being stored or queried.

6. **State transition utilities**
   - `src/utils/nextstates.go` and `src/utils/prevstates.go` provide transition logic around the graph.
   - These utilities likely generate successor states from a move and reconstruct predecessor relationships for building or verification.
   - They sit between raw board logic and the graph builder / engine logic.

7. **Constants and win logic**
   - `src/Constants/` contains the hard-coded domain tables:
     - win masks
     - symmetry tables
     - value encodings
   - These are foundational to both the builder and the runtime engine, since tic-tac-toe evaluation depends on detecting wins and mapping symmetric positions consistently.

8. **Precomputed artifacts and graph outputs**
   - The repository includes generated `.ttt` files under `bin/graph/...` and `Rust/bin/output/...`.
   - These are the serialized game graphs/maps used by the engine rather than recomputed on every run.
   - The presence of valued vs. unvalued outputs suggests the build pipeline can produce intermediate and finalized versions of the graph.

9. **Root Go application entrypoint**
   - The root `main.go` ties the Go implementation together for local execution.
   - `src/lib.go` and the package layout imply the root code can be used both as a library and as an executable.
   - The repo also includes `index.html` and browser assets, indicating the engine can be exercised visually or via wasm in a browser context.

10. **WebAssembly browser runtime**
   - `WASM/` is a separate Go module compiled to WebAssembly.
   - It packages the engine for browser execution using `main.wasm` plus `wasm_exec.js` and an HTML host page.
   - This is a runtime delivery layer, not a separate algorithmic subsystem: it exposes the same engine behavior in a browser-friendly form.

11. **Rust port and Rust WASM build**
   - `Rust/` is a Rust version of the same engine/build logic.
   - `WASM Rust/` contains the wasm-pack style browser bundle for that Rust implementation, including generated JS bindings and a `.wasm` binary.
   - Architecturally, this mirrors the Go setup: shared engine concepts, different language/runtime packaging.

12. **External and tooling boundaries**
   - The repo uses standard language toolchains only:
     - Go modules for the main and WASM Go builds
     - Cargo for the Rust build
     - wasm targets for browser execution
   - There are no obvious external services; the architecture is self-contained and file-driven.

13. **What an architecture diagram should emphasize**
   - The most important flow is:
     - **board rules + symmetry tables + win masks**
     - into **offline map construction**
     - producing **serialized game graphs**
     - consumed by the **runtime engine**
     - exposed either as a **CLI/local Go app** or a **WebAssembly browser app**
   - The main boundary is between **graph generation** and **graph consumption**; the rest of the repo supports that split.

14. **Notable duplication across languages**
   - The Go, Rust, and WASM folders largely repeat the same conceptual modules: model, engine, symmetry reduction, constants, and utilities.
   - That duplication is important for diagramming: it suggests multiple deployment targets for the same core algorithm, rather than several unrelated products.

Main entry points: [`src/mapBuilder/buildEmptyMap.go`](https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/buildEmptyMap.go) (Build empty), [`Rust/src/mapbuilder`](https://github.com/utkarsh-naman/3t/tree/main/Rust/src/mapbuilder) (Map builder), [`src/TTTEngine/3TEngine.go`](https://github.com/utkarsh-naman/3t/blob/main/src/TTTEngine/3TEngine.go) (T3 engine), [`src/Constants`](https://github.com/utkarsh-naman/3t/tree/main/src/Constants) (Constants)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_go_core["Go core"]
  node_main_go["Main app<br/>go entrypoint<br/>[main.go]"]
  node_go_constants["Constants<br/>domain tables"]
  node_go_symmetry{{"Symmetry reduction<br/>state canonicalizer"}}
  node_go_model["Game model<br/>state schema"]
  node_go_builder_empty["Build empty<br/>map stage<br/>[buildEmptyMap.go]"]
  node_go_builder_terminal["Set terminal<br/>map stage"]
  node_go_builder_values["Propagate values<br/>map stage<br/>[setValues.go]"]
  node_go_engine["T3 engine<br/>runtime engine<br/>[3TEngine.go]"]
  node_go_graph[("Game graph<br/>graph store<br/>[3TGameGraph.go]")]
  node_go_utils_next["Next states<br/>transition utility<br/>[nextstates.go]"]
  node_go_utils_prev["Prev states<br/>transition utility<br/>[prevstates.go]"]
  node_go_graph_outputs["TTT maps<br/>serialized artifacts<br/>[map1.ttt]"]
end

subgraph group_go_wasm["Go WASM"]
  node_go_wasm_main["WASM app<br/>wasm entrypoint<br/>[main.go]"]
  node_go_wasm_engine["WASM engine<br/>browser runtime<br/>[tttEngine.go]"]
  node_go_wasm_constants["WASM constants<br/>domain tables<br/>[constants.go]"]
end

subgraph group_rust_core["Rust port"]
  node_rust_lib["Rust lib<br/>crate entrypoint<br/>[lib.rs]"]
  node_rust_model["Game model<br/>state schema"]
  node_rust_builder["Map builder<br/>offline pipeline"]
  node_rust_engine["TTT engine<br/>runtime engine<br/>[ttt_engine.rs]"]
  node_rust_symmetry{{"Symmetry reduction<br/>state canonicalizer"}}
  node_rust_constants["Constants<br/>domain tables"]
  node_rust_map_outputs["TTT maps<br/>serialized artifacts<br/>[map1.ttt]"]
end

subgraph group_rust_wasm["Rust WASM"]
  node_rust_wasm_pkg["WASM package<br/>generated bundle<br/>[tte_wasm.js]"]
  node_rust_wasm_lib["WASM lib<br/>wasm crate<br/>[lib.rs]"]
  node_rust_wasm_engine["WASM engine<br/>browser runtime<br/>[ttt_engine.rs]"]
  node_rust_wasm_model["Game model<br/>state schema<br/>[state_model.rs]"]
end

node_go_constants -->|"tables"| node_go_symmetry
node_go_constants -->|"wins"| node_go_builder_terminal
node_go_constants -->|"rules"| node_go_engine
node_go_symmetry -->|"canonicalize"| node_go_builder_empty
node_go_model -->|"state schema"| node_go_builder_empty
node_go_builder_empty -->|"stage"| node_go_builder_terminal
node_go_builder_terminal -->|"stage"| node_go_builder_values
node_go_builder_values -->|"serialize"| node_go_graph_outputs
node_go_graph_outputs -->|"load"| node_go_engine
node_go_utils_next -->|"transitions"| node_go_builder_empty
node_go_utils_prev -->|"backtrack"| node_go_builder_values
node_go_graph -->|"answers"| node_go_engine
node_main_go -->|"runs"| node_go_engine
node_main_go -->|"uses"| node_go_graph_outputs
node_go_wasm_main -->|"bootstraps"| node_go_wasm_engine
node_go_wasm_constants -->|"rules"| node_go_wasm_engine
node_rust_constants -->|"tables"| node_rust_symmetry
node_rust_constants -->|"wins"| node_rust_builder
node_rust_model -->|"state schema"| node_rust_builder
node_rust_model -->|"state schema"| node_rust_engine
node_rust_symmetry -->|"canonicalize"| node_rust_builder
node_rust_builder -->|"serialize"| node_rust_map_outputs
node_rust_map_outputs -->|"load"| node_rust_engine
node_rust_lib -->|"exports"| node_rust_engine
node_rust_wasm_lib -->|"exports"| node_rust_wasm_engine
node_rust_wasm_model -->|"state schema"| node_rust_wasm_engine
node_rust_wasm_pkg -->|"bundle"| node_rust_wasm_engine

click node_main_go "https://github.com/utkarsh-naman/3t/blob/main/main.go"
click node_go_constants "https://github.com/utkarsh-naman/3t/tree/main/src/Constants"
click node_go_symmetry "https://github.com/utkarsh-naman/3t/tree/main/src/SymmetryReduction"
click node_go_model "https://github.com/utkarsh-naman/3t/tree/main/src/model"
click node_go_builder_empty "https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/buildEmptyMap.go"
click node_go_builder_terminal "https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/setTerminalValues.go"
click node_go_builder_values "https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/setValues.go"
click node_go_engine "https://github.com/utkarsh-naman/3t/blob/main/src/TTTEngine/3TEngine.go"
click node_go_graph "https://github.com/utkarsh-naman/3t/blob/main/src/TTTEngine/3TGameGraph.go"
click node_go_utils_next "https://github.com/utkarsh-naman/3t/blob/main/src/utils/nextstates.go"
click node_go_utils_prev "https://github.com/utkarsh-naman/3t/blob/main/src/utils/prevstates.go"
click node_go_graph_outputs "https://github.com/utkarsh-naman/3t/blob/main/bin/graph/valued/map1.ttt"
click node_go_wasm_main "https://github.com/utkarsh-naman/3t/blob/main/WASM/main.go"
click node_go_wasm_engine "https://github.com/utkarsh-naman/3t/blob/main/WASM/tttEngine.go"
click node_go_wasm_constants "https://github.com/utkarsh-naman/3t/blob/main/WASM/constants.go"
click node_rust_lib "https://github.com/utkarsh-naman/3t/blob/main/Rust/src/lib.rs"
click node_rust_model "https://github.com/utkarsh-naman/3t/tree/main/Rust/src/model"
click node_rust_builder "https://github.com/utkarsh-naman/3t/tree/main/Rust/src/mapbuilder"
click node_rust_engine "https://github.com/utkarsh-naman/3t/blob/main/Rust/src/game_engine/ttt_engine.rs"
click node_rust_symmetry "https://github.com/utkarsh-naman/3t/tree/main/Rust/src/symmetry_reduction"
click node_rust_constants "https://github.com/utkarsh-naman/3t/tree/main/Rust/src/constants"
click node_rust_map_outputs "https://github.com/utkarsh-naman/3t/blob/main/Rust/bin/output/map/valued/map1.ttt"
click node_rust_wasm_pkg "https://github.com/utkarsh-naman/3t/blob/main/WASM Rust/pkg/tte_wasm.js"
click node_rust_wasm_lib "https://github.com/utkarsh-naman/3t/blob/main/WASM Rust/src/lib.rs"
click node_rust_wasm_engine "https://github.com/utkarsh-naman/3t/blob/main/WASM Rust/src/ttt_engine.rs"
click node_rust_wasm_model "https://github.com/utkarsh-naman/3t/blob/main/WASM Rust/src/state_model.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_main_go,node_go_constants,node_go_symmetry,node_go_model,node_go_builder_empty,node_go_builder_terminal,node_go_builder_values,node_go_engine,node_go_graph,node_go_utils_next,node_go_utils_prev,node_go_graph_outputs toneBlue
class node_go_wasm_main,node_go_wasm_engine,node_go_wasm_constants toneAmber
class node_rust_lib,node_rust_model,node_rust_builder,node_rust_engine,node_rust_symmetry,node_rust_constants,node_rust_map_outputs toneMint
class node_rust_wasm_pkg,node_rust_wasm_lib,node_rust_wasm_engine,node_rust_wasm_model toneRose
```

## Components

### Go core

Primary Go implementation of the 3T engine and offline map builder.

- [Main app](https://github.com/utkarsh-naman/3t/blob/main/main.go): go entrypoint · Root Go executable and local entrypoint. · `main.go`
- [Constants](https://github.com/utkarsh-naman/3t/tree/main/src/Constants): domain tables · Win masks, symmetry tables, and value encodings for the game domain. · `src/Constants`
- [Symmetry reduction](https://github.com/utkarsh-naman/3t/tree/main/src/SymmetryReduction): state canonicalizer · Collapses equivalent board states under board symmetries. · `src/SymmetryReduction`
- [Game model](https://github.com/utkarsh-naman/3t/tree/main/src/model): state schema · Shared graph and state structures used by builder and engine. · `src/model`
- [Build empty](https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/buildEmptyMap.go): map stage · Initial graph construction and empty-map setup. · `src/mapBuilder/buildEmptyMap.go`
- [Set terminal](https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/setTerminalValues.go): map stage · Assigns terminal outcomes to winning and draw states. · `src/mapBuilder/setTerminalValues.go`
- [Propagate values](https://github.com/utkarsh-naman/3t/blob/main/src/mapBuilder/setValues.go): map stage · Finalizes values for non-terminal states during offline map generation. · `src/mapBuilder/setValues.go`
- [T3 engine](https://github.com/utkarsh-naman/3t/blob/main/src/TTTEngine/3TEngine.go): runtime engine · Lightweight runtime that answers from the precomputed game graph. · `src/TTTEngine/3TEngine.go`
- [Game graph](https://github.com/utkarsh-naman/3t/blob/main/src/TTTEngine/3TGameGraph.go): graph store · In-memory graph representation used by the runtime engine. · `src/TTTEngine/3TGameGraph.go`
- [Next states](https://github.com/utkarsh-naman/3t/blob/main/src/utils/nextstates.go): transition utility · Generates successor states from moves. · `src/utils/nextstates.go`
- [Prev states](https://github.com/utkarsh-naman/3t/blob/main/src/utils/prevstates.go): transition utility · Reconstructs predecessor relationships for build and verification. · `src/utils/prevstates.go`
- [TTT maps](https://github.com/utkarsh-naman/3t/blob/main/bin/graph/valued/map1.ttt): serialized artifacts · Precomputed valued and unvalued game-map outputs consumed by the engine. · `bin/graph/valued/map1.ttt`

### Go WASM

Browser-delivered Go build compiled to WebAssembly.

- [WASM app](https://github.com/utkarsh-naman/3t/blob/main/WASM/main.go): wasm entrypoint · Go WebAssembly runtime entrypoint. · `WASM/main.go`
- [WASM engine](https://github.com/utkarsh-naman/3t/blob/main/WASM/tttEngine.go): browser runtime · Browser-facing engine logic compiled to WebAssembly. · `WASM/tttEngine.go`
- [WASM constants](https://github.com/utkarsh-naman/3t/blob/main/WASM/constants.go): domain tables · Go WASM copy of the domain tables and win logic. · `WASM/constants.go`

### Rust port

Rust implementation mirroring the Go architecture.

- [Rust lib](https://github.com/utkarsh-naman/3t/blob/main/Rust/src/lib.rs): crate entrypoint · Rust library root for the ported implementation. · `Rust/src/lib.rs`
- [Game model](https://github.com/utkarsh-naman/3t/tree/main/Rust/src/model): state schema · Rust graph and state structures mirroring the Go model. · `Rust/src/model`
- [Map builder](https://github.com/utkarsh-naman/3t/tree/main/Rust/src/mapbuilder): offline pipeline · Rust offline pipeline for building and valuing the game graph. · `Rust/src/mapbuilder`
- [TTT engine](https://github.com/utkarsh-naman/3t/blob/main/Rust/src/game_engine/ttt_engine.rs): runtime engine · Rust runtime engine that queries the precomputed map. · `Rust/src/game_engine/ttt_engine.rs`
- [Symmetry reduction](https://github.com/utkarsh-naman/3t/tree/main/Rust/src/symmetry_reduction): state canonicalizer · Rust symmetry reduction layer for canonical board states. · `Rust/src/symmetry_reduction`
- [Constants](https://github.com/utkarsh-naman/3t/tree/main/Rust/src/constants): domain tables · Rust win masks, symmetry tables, and value encodings. · `Rust/src/constants`
- [TTT maps](https://github.com/utkarsh-naman/3t/blob/main/Rust/bin/output/map/valued/map1.ttt): serialized artifacts · Rust-produced serialized map outputs. · `Rust/bin/output/map/valued/map1.ttt`

### Rust WASM

Browser-delivered Rust build and generated package.

- [WASM package](https://github.com/utkarsh-naman/3t/blob/HEAD/WASM%20Rust/pkg/tte_wasm.js): generated bundle · Browser package generated from the Rust implementation. · `WASM Rust/pkg/tte_wasm.js`
- [WASM lib](https://github.com/utkarsh-naman/3t/blob/HEAD/WASM%20Rust/src/lib.rs): wasm crate · Rust WebAssembly library entrypoint. · `WASM Rust/src/lib.rs`
- [WASM engine](https://github.com/utkarsh-naman/3t/blob/HEAD/WASM%20Rust/src/ttt_engine.rs): browser runtime · Rust WebAssembly engine implementation. · `WASM Rust/src/ttt_engine.rs`
- [Game model](https://github.com/utkarsh-naman/3t/blob/HEAD/WASM%20Rust/src/state_model.rs): state schema · Rust WASM state and map structures. · `WASM Rust/src/state_model.rs`

## Connections

- Constants → Symmetry reduction: tables · Symmetry tables and encodings feed canonical reduction.
- Constants → Set terminal: wins · Win masks and values drive terminal assignment.
- Constants → T3 engine: rules · Engine uses domain encodings and win logic.
- Symmetry reduction → Build empty: canonicalize · Builder reduces states before graph construction.
- Game model → Build empty: state schema · Builder emits graph data in the shared model.
- Build empty → Set terminal: stage · Initial structure is then annotated with terminal values.
- Set terminal → Propagate values: stage · Terminal assignments feed value propagation.
- Propagate values → TTT maps: serialize · Offline pipeline writes finalized map artifacts.
- TTT maps → T3 engine: load · Runtime engine consumes the precomputed graph.
- Next states → Build empty: transitions · Successor generation supports building the graph.
- Prev states → Propagate values: backtrack · Predecessor traversal supports verification and valuation.
- Game graph → T3 engine: answers · Engine queries the graph for outcomes and choices.
- Main app → T3 engine: runs · Root executable ties the Go engine together.
- Main app → TTT maps: uses · Local execution can read generated map files.
- WASM app → WASM engine: bootstraps · Browser entrypoint starts the WebAssembly engine.
- WASM constants → WASM engine: rules · WASM engine uses the same domain tables.
- Constants → Symmetry reduction: tables · Rust symmetry reduction depends on shared constants.
- Constants → Map builder: wins · Builder uses win masks and value encodings.
- Game model → Map builder: state schema · Rust builder emits the shared model.
- Game model → TTT engine: state schema · Rust engine consumes the same graph model.
- Symmetry reduction → Map builder: canonicalize · Symmetry reduction feeds Rust map construction.
- Map builder → TTT maps: serialize · Rust pipeline writes finalized map files.
- TTT maps → TTT engine: load · Rust runtime consumes the precomputed graph.
- Rust lib → TTT engine: exports · Crate root exposes the Rust runtime components.
- WASM lib → WASM engine: exports · WebAssembly crate root exposes engine logic.
- Game model → WASM engine: state schema · WASM engine uses the Rust state model.
- WASM package → WASM engine: bundle · Generated package wraps the compiled WASM engine.