Architecture Decision Records
Key architectural decisions that shaped the system.
ADR-001: Engine-First Architecture
Context: Business logic was scattered across TUI, CLI, and utility scripts, causing duplication and inconsistency.
Decision: Centralize all business logic in the gRPC engine. TUI, CLI, and MCP become thin clients.
Consequences: Single source of truth for all operations. Engine manages GPU resources centrally. All interfaces get consistent behavior automatically. Execution of substantive workflows is delegated to platform Metaflow on Kubernetes under YuniKorn, orchestrated by the Signals Airflow; flows are engine clients over gRPC (see Engine-First and workload execution).
ADR-002: Just Over devenv-tasks
Context: devenv-tasks 2.0.0 introduced SQLite locking on tasks.db that deadlocks when tasks call devenv up.
Decision: Migrate from devenv-tasks to Just as the task runner.
Consequences: Pure command runner with no state files. Recipes defined in justfile. No locking issues. scripts/restart-clean.sh still does actual work; Just recipe delegates to it.
ADR-003: Fail-Fast as Iron-Clad Principle
Context: Silent degradation hid problems until they became critical.
Decision: All code must surface errors immediately with guru meditation codes and remediation paths. No silent fallbacks.
Consequences: Higher initial friction (more explicit error handling) but dramatically faster diagnosis and resolution. Self-healing system built on reliable error detection.
ADR-004: FMEA for Health Monitoring
Context: Simple severity classifications don’t capture risk adequately — a rare but invisible failure is more dangerous than a frequent but obvious one.
Decision: Adopt FMEA (Failure Mode and Effects Analysis) with RPN scoring for health monitoring.
Consequences: Quantitative risk assessment (S x O x D). Tiered remediation based on risk level. Adaptive learning from outcomes.
ADR-005: LuxCore Over Blender for Visualization
Context: Blender’s Cycles renderer couldn’t render glass convincingly (opaque white blobs).
Decision: Use LuxCore unbiased path tracer for card visualization, initially via PyPI, later from source for GPU acceleration.
Consequences: Physically accurate glass rendering. GPU-accelerated via PATHOCL engine with CUDA. More complex build process but superior visual quality.
ADR-006: Process Scripts Over Inline Nix Bash
Context: devenv.nix contained inline bash blocks that were hard to debug and test.
Decision: Move all process startup bash to scripts/processes/*.sh with shared helpers. devenv.nix becomes a pure service declaration file with one-liner exec blocks.
Consequences: Scripts are independently testable. Shared helpers eliminate duplication. Nix store paths passed as environment variables.
Adding New ADRs
When making significant architectural decisions:
- Add an entry here with Context, Decision, and Consequences
- Reference the ADR in relevant code comments
- Update CLAUDE.md if the decision affects development workflow