# 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
   - First vertical slice is implemented as `crates/infinity_host_ui`
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. Expand the new UI slice from mock service to real host transport adapters
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