# HyperTwist — ARCHITECTURE.md

## Product identity

HyperTwist is an all-in-one native training environment for cubes and hypercubes. Its special strength is that it joins:
- physical-world cube interaction and analysis
- virtual simulation and higher-dimensional training
- AI-guided coaching and progression

## Runtime center

The runtime center should be Unreal Engine 5.4+.

## Current landed donor truth

HyperTwist currently has a narrow landed donor truth, not a broad one:

- five permissive `MIT` donor lanes are already live in training materialization and owned source attribution
- one restrictive lane, `onionhoney/roux-trainers`, is already live through the current accepted clean-room implementation chain
- the remaining donor portfolio is still a retained architecture backlog, not a proven implemented architecture

### Why Unreal fits
Unreal is justified because HyperTwist is not merely a trainer app. It wants:
- high-quality rendering
- immersive puzzle manipulation
- spatial intuition for higher dimensions
- VR/MR expansion potential
- high-performance native runtime

## Backbone language strategy

### C++
Use for:
- puzzle-state core
- renderer integration
- interaction hot paths
- replay engine
- native timer and analytics primitives
- projection logic
- heavy simulation work

### Rust or C++
Use for:
- algorithm engines
- search and scoring
- state serialization
- progression computations
- high-throughput replay or analytics pipelines

### C#
Use only where:
- bounded profile/progression/orchestration services
- enterprise or educational admin surfaces
- durable background jobs
are clearly beneficial

### Python / TypeScript
Keep bounded:
- Python for CV or model inference where still practical
- TypeScript for thin dashboard or companion UI surfaces only

## Dual-pillar architecture

### Pillar 1 — physical cube pipeline
- camera input
- state recognition
- confidence and correction UI
- solve reconstruction
- replay generation
- AI commentary and drill suggestions

### Pillar 2 — hypercube simulation pipeline
- n-dimensional puzzle model
- rendering and projection
- notation teaching
- immersive manipulation
- advanced user workflows
- compatibility with known hypercubing formats where worthwhile

## Subsystem proposal

- `HyperTwistCore`
- `HyperTwistSimulation`
- `HyperTwistRecognition`
- `HyperTwistReplay`
- `HyperTwistTraining`
- `HyperTwistCoach`
- `HyperTwistProgression`
- `HyperTwistXR`

## Integration policy

### Foundation candidates
Treat true simulation cores and essential logic frameworks separately from:
- wrappers
- ports
- UI frameworks
- ecosystem experiments

### CV candidates
Likely best as bounded services or donor modules first unless one is simple and directly embeddable.

### Trainer candidates
Often strategic donors rather than foundations.

Current correction:

- the currently landed trainer donor set is small and explicit
- do not treat all selected trainer repos as already architecturally absorbed

### Hyper tools
Need to be judged for:
- algorithmic depth
- notation compatibility
- rendering value
- interoperability with the rest of the stack

## Provenance control plane

Architecture decisions for HyperTwist must now preserve three visibly separate layers:

- landed/live first-party implementation
- retained donor backlog pending deep evaluation
- restrictive clean-room or benchmark/reference lanes

That provenance split is part of the architecture, not just part of legal paperwork.

## Unreal/XR posture

HyperTwist benefits from:
- controller and hand-based manipulation
- spatial coaching overlays
- higher-dimensional explanatory projection
- embodied replay and algorithm walkthroughs

The immersive mode is not the whole product, but it is a major differentiator.
