# fightandsurvive/helix architecture

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

- Interactive diagram: https://gitdiagram.com/fightandsurvive/helix
- Repository: https://github.com/fightandsurvive/helix

## Overview

Helix is a local-first chess workstation combining the Trinstinctus neural MCTS engine, a multi-voice coaching panel, personal-game analytics, training, and opening/puzzle tools. The main user flow runs from the React tabs through Tauri IPC to Rust commands and persisted data or engine services; the UCI adapter also exposes the engine to external chess clients. Python provides engine search and training, while ingest and analytics support the workstation’s data features. Some UI and Rust subsystems are represented from the tree and README; their internal calls were not sampled, so those links are documented only where the README supports them.

Main entry points: [`app/src-tauri/src/lib.rs`](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/lib.rs) (Tauri commands), [`app/src/App.tsx`](https://github.com/fightandsurvive/helix/blob/main/app/src/App.tsx) (Helix tabs), [`training/orchestrator.py`](https://github.com/fightandsurvive/helix/blob/main/training/orchestrator.py) (Training orchestrator), [`engine/mcts.py`](https://github.com/fightandsurvive/helix/blob/main/engine/mcts.py) (MCTS search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workstation UI"]
  node_app["Helix tabs<br/>[App.tsx]"]
  node_invoke["Tauri invoke<br/>[useInvoke.ts]"]
  node_play["Play board<br/>[PlayTab.tsx]"]
  node_puzzles["Puzzle trainer<br/>[PuzzleTrainer.tsx]"]
  node_weakness["Weakness finder<br/>[WeaknessFinder.tsx]"]
end

subgraph group_backend["Desktop Backend"]
  node_rust["Tauri commands<br/>[lib.rs]"]
  node_enginebridge["Engine bridge<br/>[engine_bridge.rs]"]
  node_panel["Coach panel service<br/>[panel_service.rs]"]
  node_playbackend["Play services<br/>[play.rs]"]
  node_puzzlebackend["Daily puzzle<br/>[daily_puzzle.rs]"]
end

subgraph group_engine["Chess Engine"]
  node_mcts["MCTS search<br/>[mcts.py]"]
  node_model["Transformer model<br/>[model.py]"]
  node_uci["UCI adapter<br/>[uci_engine.py]"]
  node_legends["Seven-voice tutor<br/>[panel_service.py]"]
end

subgraph group_data["Game Data"]
  node_store[("PostgreSQL")]
  node_importer["Game import<br/>[personal.rs]"]
  node_analytics["Game analytics<br/>[weakness.py]"]
  node_accuracy["Accuracy worker<br/>[accuracy_worker.py]"]
  node_ingest["PGN and puzzle ingest"]
end

subgraph group_learning["Training System"]
  node_orchestrator["Training orchestrator<br/>[orchestrator.py]"]
  node_supervised["Supervised bootstrap"]
  node_distill["Stockfish distillation<br/>[distill.py]"]
  node_rl["Self-play RL<br/>[train_rl.py]"]
  node_adapters["Legend adapters<br/>[train_adapters.py]"]
end

node_player(("Chess user"))
node_stockfish["Stockfish"]
node_chessclient(("Chess GUI"))

node_player -->|"uses"| node_app
node_app -->|"renders"| node_play
node_app -->|"renders"| node_puzzles
node_app -->|"renders"| node_weakness
node_app -->|"requests commands"| node_invoke
node_invoke -->|"IPC invokes"| node_rust
node_rust -->|"queries and writes"| node_store
node_rust -->|"dispatches"| node_enginebridge
node_rust -->|"dispatches"| node_panel
node_rust -->|"dispatches"| node_playbackend
node_rust -->|"dispatches"| node_puzzlebackend
node_playbackend -->|"persists game data"| node_store
node_puzzlebackend -->|"reads puzzle data"| node_store
node_importer -->|"stores imported games"| node_store
node_ingest -->|"loads game data"| node_store
node_accuracy -->|"reads and writes results"| node_store
node_analytics -->|"analyzes game records"| node_store
node_enginebridge -.->|"requests analysis"| node_mcts
node_uci -->|"searches positions"| node_mcts
node_mcts -->|"evaluates leaves"| node_model
node_legends -->|"loads base model"| node_model
node_legends -->|"consults oracle"| node_stockfish
node_chessclient -->|"sends UCI commands"| node_uci
node_orchestrator -->|"runs self-play stage"| node_rl
node_supervised -.->|"trains model"| node_model
node_distill -->|"distills from"| node_stockfish
node_orchestrator -.->|"begins training pipeline"| node_supervised
node_orchestrator -.->|"runs training stage"| node_distill
node_orchestrator -.->|"trains after freeze"| node_adapters
node_rl -->|"generates self-play targets"| node_mcts
node_adapters -.->|"supplies voice adapters"| node_legends

click node_app "https://github.com/fightandsurvive/helix/blob/main/app/src/App.tsx"
click node_invoke "https://github.com/fightandsurvive/helix/blob/main/app/src/hooks/useInvoke.ts"
click node_play "https://github.com/fightandsurvive/helix/blob/main/app/src/components/PlayTab.tsx"
click node_puzzles "https://github.com/fightandsurvive/helix/blob/main/app/src/components/PuzzleTrainer.tsx"
click node_weakness "https://github.com/fightandsurvive/helix/blob/main/app/src/components/WeaknessFinder.tsx"
click node_rust "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/lib.rs"
click node_enginebridge "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/engine_bridge.rs"
click node_panel "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/panel_service.rs"
click node_playbackend "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/play.rs"
click node_puzzlebackend "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/daily_puzzle.rs"
click node_importer "https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/personal.rs"
click node_analytics "https://github.com/fightandsurvive/helix/blob/main/analytics/weakness.py"
click node_accuracy "https://github.com/fightandsurvive/helix/blob/main/training/accuracy_worker.py"
click node_ingest "https://github.com/fightandsurvive/helix/tree/main/ingest"
click node_mcts "https://github.com/fightandsurvive/helix/blob/main/engine/mcts.py"
click node_model "https://github.com/fightandsurvive/helix/blob/main/engine/model.py"
click node_uci "https://github.com/fightandsurvive/helix/blob/main/engine/uci_engine.py"
click node_legends "https://github.com/fightandsurvive/helix/blob/main/engine/panel_service.py"
click node_orchestrator "https://github.com/fightandsurvive/helix/blob/main/training/orchestrator.py"
click node_supervised "https://github.com/fightandsurvive/helix/blob/main/training/train_supervised.py"
click node_distill "https://github.com/fightandsurvive/helix/blob/main/training/distill.py"
click node_rl "https://github.com/fightandsurvive/helix/blob/main/training/train_rl.py"
click node_adapters "https://github.com/fightandsurvive/helix/blob/main/training/train_adapters.py"

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_app,node_invoke,node_play,node_puzzles,node_weakness,node_player,node_chessclient toneBlue
class node_rust,node_enginebridge,node_panel,node_playbackend,node_puzzlebackend toneAmber
class node_mcts,node_model,node_uci,node_legends toneMint
class node_store,node_importer,node_analytics,node_accuracy,node_ingest toneRose
class node_orchestrator,node_supervised,node_distill,node_rl,node_adapters,node_stockfish toneIndigo
```

## Components

### Workstation UI

- [Helix tabs](https://github.com/fightandsurvive/helix/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Tauri invoke](https://github.com/fightandsurvive/helix/blob/main/app/src/hooks/useInvoke.ts): `app/src/hooks/useInvoke.ts`
- [Play board](https://github.com/fightandsurvive/helix/blob/main/app/src/components/PlayTab.tsx): `app/src/components/PlayTab.tsx`
- [Puzzle trainer](https://github.com/fightandsurvive/helix/blob/main/app/src/components/PuzzleTrainer.tsx): `app/src/components/PuzzleTrainer.tsx`
- [Weakness finder](https://github.com/fightandsurvive/helix/blob/main/app/src/components/WeaknessFinder.tsx): `app/src/components/WeaknessFinder.tsx`

### Desktop Backend

- [Tauri commands](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/lib.rs): `app/src-tauri/src/lib.rs`
- [Engine bridge](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/engine_bridge.rs): `app/src-tauri/src/engine_bridge.rs`
- [Coach panel service](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/panel_service.rs): `app/src-tauri/src/panel_service.rs`
- [Play services](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/play.rs): `app/src-tauri/src/play.rs`
- [Daily puzzle](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/daily_puzzle.rs): `app/src-tauri/src/daily_puzzle.rs`

### Chess Engine

- [MCTS search](https://github.com/fightandsurvive/helix/blob/main/engine/mcts.py): `engine/mcts.py`
- [Transformer model](https://github.com/fightandsurvive/helix/blob/main/engine/model.py): `engine/model.py`
- [UCI adapter](https://github.com/fightandsurvive/helix/blob/main/engine/uci_engine.py): `engine/uci_engine.py`
- [Seven-voice tutor](https://github.com/fightandsurvive/helix/blob/main/engine/panel_service.py): `engine/panel_service.py`

### Game Data

- **PostgreSQL**
- [Game import](https://github.com/fightandsurvive/helix/blob/main/app/src-tauri/src/personal.rs): `app/src-tauri/src/personal.rs`
- [Game analytics](https://github.com/fightandsurvive/helix/blob/main/analytics/weakness.py): `analytics/weakness.py`
- [Accuracy worker](https://github.com/fightandsurvive/helix/blob/main/training/accuracy_worker.py): `training/accuracy_worker.py`
- [PGN and puzzle ingest](https://github.com/fightandsurvive/helix/tree/main/ingest): `ingest`

### Training System

- [Training orchestrator](https://github.com/fightandsurvive/helix/blob/main/training/orchestrator.py): `training/orchestrator.py`
- [Supervised bootstrap](https://github.com/fightandsurvive/helix/blob/main/training/train_supervised.py): `training/train_supervised.py`
- [Stockfish distillation](https://github.com/fightandsurvive/helix/blob/main/training/distill.py): `training/distill.py`
- [Self-play RL](https://github.com/fightandsurvive/helix/blob/main/training/train_rl.py): `training/train_rl.py`
- [Legend adapters](https://github.com/fightandsurvive/helix/blob/main/training/train_adapters.py): `training/train_adapters.py`

### Other components

- **Chess user**
- **Stockfish**
- **Chess GUI**

## Connections

- Chess user → Helix tabs: uses
- Helix tabs → Play board: renders (evidence: `app/src/App.tsx`)
- Helix tabs → Puzzle trainer: renders (evidence: `app/src/App.tsx`)
- Helix tabs → Weakness finder: renders (evidence: `app/src/App.tsx`)
- Helix tabs → Tauri invoke: requests commands (evidence: `app/src/hooks/useInvoke.ts`)
- Tauri invoke → Tauri commands: IPC invokes
- Tauri commands → PostgreSQL: queries and writes
- Tauri commands → Engine bridge: dispatches (evidence: `app/src-tauri/src/engine_bridge.rs`)
- Tauri commands → Coach panel service: dispatches
- Tauri commands → Play services: dispatches
- Tauri commands → Daily puzzle: dispatches
- Play services → PostgreSQL: persists game data
- Daily puzzle → PostgreSQL: reads puzzle data
- Game import → PostgreSQL: stores imported games
- PGN and puzzle ingest → PostgreSQL: loads game data
- Accuracy worker → PostgreSQL: reads and writes results (evidence: `training/accuracy_worker.py`)
- Game analytics → PostgreSQL: analyzes game records (evidence: `analytics/weakness.py`)
- Engine bridge → MCTS search: requests analysis
- UCI adapter → MCTS search: searches positions (evidence: `engine/uci_engine.py`)
- MCTS search → Transformer model: evaluates leaves (evidence: `engine/mcts.py`)
- Seven-voice tutor → Transformer model: loads base model (evidence: `engine/panel_service.py`)
- Seven-voice tutor → Stockfish: consults oracle
- Chess GUI → UCI adapter: sends UCI commands (evidence: `engine/uci_engine.py`)
- Training orchestrator → Self-play RL: runs self-play stage (evidence: `training/orchestrator.py`)
- Supervised bootstrap → Transformer model: trains model
- Stockfish distillation → Stockfish: distills from
- Training orchestrator → Supervised bootstrap: begins training pipeline
- Training orchestrator → Stockfish distillation: runs training stage
- Training orchestrator → Legend adapters: trains after freeze
- Self-play RL → MCTS search: generates self-play targets (evidence: `training/train_rl.py`)
- Legend adapters → Seven-voice tutor: supplies voice adapters
