ACCEPTEDRoadmap: V3.02026-09-06 — updated 2026-09-06
ADR-004: Deterministic 3D force-directed knowledge graph
Use Three.js and deterministic pseudo-random force layout for the 3D living brain instead of dynamic unseeded physics.
Launch stateThese entries are placeholders while the real case studies and experiment write-ups are prepared for publication.
Context
- The home experience required an interactive 3D knowledge map connecting systems, case studies, ADRs, and technologies.
- Dynamic physics simulations that run indefinitely cause high CPU/GPU load on client devices and jitter the camera.
- Users returning to the site need spatial memory: nodes must appear in the exact same coordinates across sessions and devices.
Decision
- Use React Three Fiber (@react-three/fiber) with @react-three/drei for declarative WebGL rendering.
- Compute node positions deterministically using an FNV-1a seeded PRNG and multi-iteration Coulomb-Hooke relaxation at build/load time.
- Provide an accessible static fallback view (HomeStatic) respecting prefers-reduced-motion and devices without WebGL.
Alternatives considered
- 2D SVG canvas exclusively. Rejected because it lacks depth perception for multi-layer relationship hierarchies.
- Real-time continuous physics engine (Rapier / Cannon). Rejected due to excessive battery consumption and nondeterministic positioning.
Consequences
- Instant, reproducible spatial graph rendering with zero runtime physics calculations.
- Spatial anchoring enables smooth camera flight transitions when Jarvis cites specific nodes.
- Edge count must be budgeted via pruning heuristics to keep draw calls performant on mobile GPUs.
Roadmap & Marcos de Implementação
V3.0Living Brain 3D Spatial Knowledge
Progresso da Execução Arquitetural100% CONCLUÍDO
- React Three Fiber & Drei Setup(Phase 1: WebGL Declarative Engine)Concluído
Implemented smooth WebGL canvas lifecycle, responsive ResizeObserver integration, and high-performance render loops.
- FNV-1a PRNG Coulomb-Hooke Relaxation(Phase 2: Deterministic Spatial Mathematics)Concluído
Eliminated jitter and dynamic physics battery drain by pre-computing exact, reproducible 3D node coordinates at startup.
- Mobile GPU Draw Call Optimization(Phase 3: Edge Budgeting Heuristics)Concluído
Budgeted visual edges via similarity pruning thresholds to keep draw calls lightweight across smartphone hardware.
- Static Semantic List (HomeStatic)(Phase 4: Universal Accessibility Fallback)Concluído
Delivered comprehensive WCAG-compliant static list fallback honoring prefers-reduced-motion and non-WebGL environments.