How fightandsurvive/helix works
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: lib.rs Tauri commands · App.tsx Helix tabs · orchestrator.py Training orchestrator · mcts.py MCTS search
Components 27
Workstation UI
- Helix tabs
app/src/App.tsx - Tauri invoke
app/src/hooks/useInvoke.ts - Play board
app/src/components/PlayTab.tsx - Puzzle trainer
app/src/components/PuzzleTrainer.tsx - Weakness finder
app/src/components/WeaknessFinder.tsx
Desktop Backend
- Tauri commands
app/src-tauri/src/lib.rs - Engine bridge
app/src-tauri/src/engine_bridge.rs - Coach panel service
app/src-tauri/src/panel_service.rs - Play services
app/src-tauri/src/play.rs - Daily puzzle
app/src-tauri/src/daily_puzzle.rs
Chess Engine
- MCTS search
engine/mcts.py - Transformer model
engine/model.py - UCI adapter
engine/uci_engine.py - Seven-voice tutor
engine/panel_service.py
Game Data
- PostgreSQL
- Game import
app/src-tauri/src/personal.rs - Game analytics
analytics/weakness.py - Accuracy worker
training/accuracy_worker.py - PGN and puzzle ingest
ingest
Training System
- Training orchestrator
training/orchestrator.py - Supervised bootstrap
training/train_supervised.py - Stockfish distillation
training/distill.py - Self-play RL
training/train_rl.py - Legend adapters
training/train_adapters.py
Other components
- Chess user
- Stockfish
- Chess GUI
Connections 31
- Chess user → Helix tabs: uses
- Helix tabs → Play board: renders
app/src/App.tsx - Helix tabs → Puzzle trainer: renders
app/src/App.tsx - Helix tabs → Weakness finder: renders
app/src/App.tsx - Helix tabs → Tauri invoke: requests commands
app/src/hooks/useInvoke.ts - Tauri invoke → Tauri commands: IPC invokes
- Tauri commands → PostgreSQL: queries and writes
- Tauri commands → Engine bridge: dispatches
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
training/accuracy_worker.py - Game analytics → PostgreSQL: analyzes game records
analytics/weakness.py - Engine bridge → MCTS search: requests analysis
- UCI adapter → MCTS search: searches positions
engine/uci_engine.py - MCTS search → Transformer model: evaluates leaves
engine/mcts.py - Seven-voice tutor → Transformer model: loads base model
engine/panel_service.py - Seven-voice tutor → Stockfish: consults oracle
- Chess GUI → UCI adapter: sends UCI commands
engine/uci_engine.py - Training orchestrator → Self-play RL: runs self-play stage
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
training/train_rl.py - Legend adapters → Seven-voice tutor: supplies voice adapters