2.8 KiB
2.8 KiB
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+.
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
HyperTwistCoreHyperTwistSimulationHyperTwistRecognitionHyperTwistReplayHyperTwistTrainingHyperTwistCoachHyperTwistProgressionHyperTwistXR
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.
Hyper tools
Need to be judged for:
- algorithmic depth
- notation compatibility
- rendering value
- interoperability with the rest of the stack
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.