# tig-foundation/tig-monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/tig-foundation/tig-monorepo
- Repository: https://github.com/tig-foundation/tig-monorepo

## Overview

#### Purpose and Top-Level Entry Points
TIG is a monorepo implementing an optimisable proof-of-work network: innovators submit challenge solvers; benchmarkers execute them, produce proofs/runtime signatures, and protocol logic validates rewards. Rust is the primary systems language, with CUDA for GPU challenges, Python for benchmark orchestration, Solidity for the token, and Angular for the operational dashboard.

Primary executable entry points are `tig-runtime/src/main.rs` (single-nonce execution), `tig-verifier/src/main.rs` (solution/proof verification), and benchmarker processes at `tig-benchmarker/master/main.py` and `tig-benchmarker/slave/main.py`.

#### Shared Domain and Protocol Layer
Shared Rust types define challenge instances, solutions, configuration, and protocol-facing data. Core utilities provide deterministic hashing, serialization, Merkle trees, Ethereum support, and numerical helpers.
- `tig-structs/src/core.rs`
- `tig-structs/src/config.rs`
- `tig-utils/src/merkle_tree.rs`
- `tig-protocol/src/contracts/benchmarks.rs`
- `tig-protocol/src/contracts/opow.rs`

Protocol contracts organize algorithms, benchmarks, players, rewards, and OPoW state transitions; this is the boundary between benchmark evidence and consensus/reward accounting.

#### Challenge Definition and Evaluation Boundary
Eight challenge domains implement deterministic problem generation, validation, scoring, and baseline solvers. They are selected by challenge ID/type and form the contract that algorithm implementations must satisfy. CPU and GPU workloads coexist; GPU domains include CUDA kernels.
- `tig-challenges/src/lib.rs`
- `tig-challenges/src/satisfiability/mod.rs`
- `tig-challenges/src/vector_search/mod.rs`
- `tig-challenges/src/hypergraph/kernels.cu`
- `tig-challenges/src/neuralnet_optimizer/nn/mod.rs`

The central flow is nonce/input → challenge instance → submitted solver → candidate solution → challenge validation/score and measured execution signature/fuel.

#### Algorithm Submission Library
`tig-algorithms` is a registry of versioned, challenge-specific solver submissions. Domain modules expose implementations; individual solver directories isolate alternative algorithms and track-specialized strategies. Published archives in `lib/` are distributable algorithm artifacts.
- `tig-algorithms/src/lib.rs`
- `tig-algorithms/src/vehicle_routing/mod.rs`
- `tig-algorithms/src/vehicle_routing/hgs_advance/solver.rs`
- `tig-algorithms/src/job_scheduling/adaptive_js/solver.rs`
- `tig-algorithms/lib/vector_search/`

GPU-capable submissions pair Rust dispatch/wrappers with CUDA source, such as `tig-algorithms/src/hypergraph/sigma_freud_v8/mod.rs` and its track-specific kernels.

#### Compilation and Isolated Runtime
The binary crate wraps an algorithm into a shared-object ABI and provides CUDA framework support. Runtime loads/executes that compiled algorithm for one nonce, producing fuel consumption and a runtime signature; verifier independently checks the resulting solution or Merkle proof.
- `tig-binary/src/entry_point_template.rs`
- `tig-binary/src/lib.rs`
- `tig-binary/src/framework.cu`
- `tig-runtime/src/main.rs`
- `tig-verifier/src/main.rs`

Build scripts under `tig-binary/scripts/` establish the Rust/CUDA-to-`.so` packaging boundary; runtime Docker images enforce the challenge-specific execution environment.

#### Distributed Benchmarker Control Plane
A Python master/slave system schedules benchmark jobs, fetches data, manages algorithm submissions and precommits, and persists operational state in PostgreSQL. Slaves execute challenge runtime containers and return benchmark/proof results to the master.
- `tig-benchmarker/master/master/job_manager.py`
- `tig-benchmarker/master/master/slave_manager.py`
- `tig-benchmarker/master/master/precommit_manager.py`
- `tig-benchmarker/slave/main.py`
- `tig-benchmarker/master/master/sql.py`

Deployment is Docker Compose-oriented: `tig-benchmarker/master.yml` composes master, PostgreSQL, UI, and Nginx; `tig-benchmarker/slave.yml` provisions worker orchestration plus runtime images.

#### External Interfaces and Operations
The benchmarker dashboard is an Angular client behind Nginx, consuming benchmarker APIs. Ethereum/Base-chain integration is represented by protocol/token code and Rust Ethereum utilities. Docker images are published through GitHub Packages for amd64 and arm64; GPU workloads additionally require CUDA-capable runtime environments.
- `tig-benchmarker/ui/src/app/services/tig-apis.service.ts`
- `tig-benchmarker/nginx/nginx.conf`
- `tig-token/TIGToken.sol`
- `tig-token/TokenLocker.sol`
- `tig-utils/src/eth.rs`

Main entry points: [`tig-benchmarker/master/main.py`](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/master/main.py) (Benchmarker master), [`tig-challenges/src/lib.rs`](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-challenges/src/lib.rs) (Challenge evaluation), [`tig-runtime/src/main.rs`](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-runtime/src/main.rs) (Single-nonce runtime), [`tig-protocol/src/contracts/opow.rs`](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-protocol/src/contracts/opow.rs) (OPoW protocol contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["Domain & Protocol"]
  node_structs["Shared domain types<br/>Rust crate<br/>[core.rs]"]
  node_utils["Deterministic utilities<br/>Rust crate<br/>[merkle_tree.rs]"]
  node_challenges["Challenge evaluation<br/>Rust crate<br/>[lib.rs]"]
  node_cuda_challenges["Challenge CUDA kernels<br/>CUDA source<br/>[kernels.cu]"]
  node_protocol["OPoW protocol contracts<br/>Rust protocol<br/>[opow.rs]"]
end

subgraph group_algorithms["Solver Packaging"]
  node_algorithms_registry["Solver submission registry<br/>Rust crate<br/>[lib.rs]"]
  node_solver_implementation["Specialized solver<br/>Rust solver<br/>[solver.rs]"]
  node_algorithm_artifacts["Published solver archives<br/>algorithm artifacts"]
end

subgraph group_execution["Execution &amp; Verification"]
  node_binary_abi["Shared-object ABI wrapper<br/>Rust/CUDA build crate<br/>[lib.rs]"]
  node_cuda_framework["CUDA runtime framework<br/>CUDA source<br/>[framework.cu]"]
  node_runtime{{"Single-nonce runtime<br/>Rust executable<br/>[main.rs]"}}
  node_verifier{{"Solution/proof verifier<br/>Rust executable<br/>[main.rs]"}}
end

subgraph group_benchmarker["Benchmarker Control Plane"]
  node_master["Benchmarker master<br/>Python service<br/>[main.py]"]
  node_slave["Benchmarker slave<br/>Python worker<br/>[main.py]"]
  node_postgres[("Operational state<br/>PostgreSQL<br/>[sql.py]")]
end

subgraph group_operations["External Operations"]
  node_dashboard["Operations dashboard<br/>Angular client"]
  node_nginx["Dashboard gateway<br/>Nginx<br/>[nginx.conf]"]
  node_token["TIG token contracts<br/>Solidity contracts<br/>[TIGToken.sol]"]
end

node_structs -->|"instances and solutions"| node_challenges
node_utils -->|"deterministic primitives"| node_challenges
node_cuda_challenges -->|"GPU domains"| node_challenges
node_challenges -->|"solver contract"| node_algorithms_registry
node_algorithms_registry -->|"contains"| node_solver_implementation
node_algorithms_registry -->|"publishes"| node_algorithm_artifacts
node_solver_implementation -->|"wrapped for execution"| node_binary_abi
node_binary_abi -->|"GPU support"| node_cuda_framework
node_binary_abi -->|"loads shared object"| node_runtime
node_runtime -->|"candidate solution"| node_challenges
node_runtime -->|"solution, signature, proof"| node_verifier
node_verifier -->|"validated evidence"| node_protocol
node_utils -->|"Merkle and Ethereum support"| node_protocol
node_protocol -->|"reward/token integration"| node_token
node_master -->|"schedules benchmark jobs"| node_slave
node_slave -->|"executes runtime containers"| node_runtime
node_slave -->|"benchmark and proof results"| node_master
node_master -->|"persists state"| node_postgres
node_dashboard -->|"served through"| node_nginx
node_nginx -->|"benchmarker API"| node_master
node_master -->|"submits benchmark evidence"| node_protocol

click node_structs "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-structs/src/core.rs"
click node_utils "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-utils/src/merkle_tree.rs"
click node_challenges "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-challenges/src/lib.rs"
click node_cuda_challenges "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-challenges/src/hypergraph/kernels.cu"
click node_protocol "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-protocol/src/contracts/opow.rs"
click node_algorithms_registry "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-algorithms/src/lib.rs"
click node_solver_implementation "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-algorithms/src/vehicle_routing/hgs_advance/solver.rs"
click node_binary_abi "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-binary/src/lib.rs"
click node_cuda_framework "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-binary/src/framework.cu"
click node_runtime "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-runtime/src/main.rs"
click node_verifier "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-verifier/src/main.rs"
click node_master "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/master/main.py"
click node_slave "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/slave/main.py"
click node_postgres "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/master/master/sql.py"
click node_dashboard "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/ui/src/app/services/tig-apis.service.ts"
click node_nginx "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/nginx/nginx.conf"
click node_token "https://github.com/tig-foundation/tig-monorepo/blob/main/tig-token/TIGToken.sol"

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_structs,node_utils,node_challenges,node_cuda_challenges,node_protocol toneBlue
class node_algorithms_registry,node_solver_implementation,node_algorithm_artifacts toneAmber
class node_binary_abi,node_cuda_framework,node_runtime,node_verifier toneMint
class node_master,node_slave,node_postgres toneRose
class node_dashboard,node_nginx,node_token toneIndigo
```

## Components

### Domain & Protocol

- [Shared domain types](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-structs/src/core.rs): Rust crate · Challenge, solution, configuration, and protocol data. · `tig-structs/src/core.rs`
- [Deterministic utilities](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-utils/src/merkle_tree.rs): Rust crate · Hashing, serialization, Merkle, numerical, and Ethereum helpers. · `tig-utils/src/merkle_tree.rs`
- [Challenge evaluation](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-challenges/src/lib.rs): Rust crate · Eight deterministic domains generate, validate, and score solutions. · `tig-challenges/src/lib.rs`
- [Challenge CUDA kernels](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-challenges/src/hypergraph/kernels.cu): CUDA source · `tig-challenges/src/hypergraph/kernels.cu`
- [OPoW protocol contracts](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-protocol/src/contracts/opow.rs): Rust protocol · Transforms benchmark evidence into consensus and reward state. · `tig-protocol/src/contracts/opow.rs`

### Solver Packaging

- [Solver submission registry](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-algorithms/src/lib.rs): Rust crate · Versioned challenge-specific solver implementations. · `tig-algorithms/src/lib.rs`
- [Specialized solver](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-algorithms/src/vehicle_routing/hgs_advance/solver.rs): Rust solver · Track-specialized algorithm implementation. · `tig-algorithms/src/vehicle_routing/hgs_advance/solver.rs`
- **Published solver archives**: algorithm artifacts · Distributable solver submissions.

### Execution & Verification

- [Shared-object ABI wrapper](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-binary/src/lib.rs): Rust/CUDA build crate · Packages a solver behind the runtime shared-object ABI. · `tig-binary/src/lib.rs`
- [CUDA runtime framework](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-binary/src/framework.cu): CUDA source · `tig-binary/src/framework.cu`
- [Single-nonce runtime](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-runtime/src/main.rs): Rust executable · Executes a compiled solver and emits fuel and runtime signature. · `tig-runtime/src/main.rs`
- [Solution/proof verifier](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-verifier/src/main.rs): Rust executable · Independently validates solutions or Merkle proofs. · `tig-verifier/src/main.rs`

### Benchmarker Control Plane

- [Benchmarker master](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/master/main.py): Python service · Schedules jobs and coordinates submissions, precommits, and workers. · `tig-benchmarker/master/main.py`
- [Benchmarker slave](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/slave/main.py): Python worker · Runs challenge runtime containers and returns results. · `tig-benchmarker/slave/main.py`
- [Operational state](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/master/master/sql.py): PostgreSQL · Persists benchmarker state. · `tig-benchmarker/master/master/sql.py`

### External Operations

- [Operations dashboard](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/ui/src/app/services/tig-apis.service.ts): Angular client · `tig-benchmarker/ui/src/app/services/tig-apis.service.ts`
- [Dashboard gateway](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-benchmarker/nginx/nginx.conf): Nginx · `tig-benchmarker/nginx/nginx.conf`
- [TIG token contracts](https://github.com/tig-foundation/tig-monorepo/blob/main/tig-token/TIGToken.sol): Solidity contracts · On-chain token and locking interface. · `tig-token/TIGToken.sol`

## Connections

- Shared domain types → Challenge evaluation: instances and solutions
- Deterministic utilities → Challenge evaluation: deterministic primitives
- Challenge CUDA kernels → Challenge evaluation: GPU domains
- Challenge evaluation → Solver submission registry: solver contract
- Solver submission registry → Specialized solver: contains
- Solver submission registry → Published solver archives: publishes
- Specialized solver → Shared-object ABI wrapper: wrapped for execution
- Shared-object ABI wrapper → CUDA runtime framework: GPU support
- Shared-object ABI wrapper → Single-nonce runtime: loads shared object
- Single-nonce runtime → Challenge evaluation: candidate solution
- Single-nonce runtime → Solution/proof verifier: solution, signature, proof
- Solution/proof verifier → OPoW protocol contracts: validated evidence
- Deterministic utilities → OPoW protocol contracts: Merkle and Ethereum support
- OPoW protocol contracts → TIG token contracts: reward/token integration
- Benchmarker master → Benchmarker slave: schedules benchmark jobs
- Benchmarker slave → Single-nonce runtime: executes runtime containers
- Benchmarker slave → Benchmarker master: benchmark and proof results
- Benchmarker master → Operational state: persists state
- Operations dashboard → Dashboard gateway: served through
- Dashboard gateway → Benchmarker master: benchmarker API
- Benchmarker master → OPoW protocol contracts: submits benchmark evidence