# 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