Initial commit

docs/architecture.md

@@ -0,0 +1,85 @@
+# Architecture
+
+## Goal
+
+Build a live-capable LED control platform that keeps realtime output deterministic while letting operators change scenes, brightness, tests, and presets without UI jitter leaking into the hot path.
+
+## Layer Split
+
+1. Control layer
+   - Operator workflow
+   - Presets and topology editing
+   - Monitoring and diagnostics
+   - Never the timing master for LED output
+2. Realtime engine
+   - Owns the monotonic clock
+   - Computes scene state, transitions, and dirty regions
+   - Produces transport-ready commands or pixel frames
+3. Transport and node layer
+   - Discovery, heartbeat, config sync, sequencing, and recovery
+   - Control protocol and realtime protocol stay separate
+   - Latest realtime state wins, stale frames may be dropped
+4. ESP32 firmware
+   - Receives commands
+   - Maintains local buffers
+   - Drives three independent outputs per node
+   - Handles watchdog and reconnect logic locally
+
+## Runtime Model
+
+- Logic tick target: 120 Hz
+- Frame synthesis target: 60 Hz
+- Network send target: 40-60 Hz, profile dependent
+- Preview target: 10-15 Hz
+
+Preview and telemetry are explicitly degradable. Realtime output is not.
+
+## Modes
+
+### Distributed Scene Mode
+
+- Default operating mode
+- Host sends scene parameters, time basis, seed, palette, and transitions
+- Nodes render locally for low bandwidth and better resilience
+
+### Frame Streaming Mode
+
+- Used for mapping tests, debugging, and effects that cannot run node-local
+- Host sends explicit output frames
+- Kept logically separate so it does not contaminate the primary scene pipeline
+
+## Mapping Model
+
+The project configuration separates mapping into three layers:
+
+1. Hardware mapping
+   - Node ID
+   - Top, middle, bottom output
+   - Physical output label
+   - Driver channel reference
+   - LED count, direction, color order, enable flag
+2. Layout mapping
+   - Optional row and column placement
+   - Optional preview transforms only
+3. Group mapping
+   - Explicit groups for artistic control and fast operator access
+
+The current example config intentionally keeps layout mapping empty because the old XML is only a spatial reference and the final node-to-room placement must still be confirmed on real hardware.
+
+## Validation Gates
+
+The codebase deliberately blocks activation when these remain unresolved:
+
+- `UART 6`, `UART 5`, `UART 4` still marked as `pending_validation`
+- output validation state is not `validated`
+- LED count deviates from 106
+- node outputs are missing top, middle, or bottom
+- driver references are ambiguous or duplicated per node
+
+## Planned Next Steps
+
+1. Add the actual UI adapter on top of `infinity_host`
+2. Implement UDP transport with separate control and realtime sockets
+3. Connect firmware driver backends after hardware validation
+4. Add deterministic effect registry shared between host planning and firmware capability negotiation
+