# Infinity_Vis_1 Architecture

## Design goal

Make the render path cheaper than the current application by replacing
object-heavy frame construction with a compact, controller-oriented runtime.

## High-level layers

1. `mapping_xml.py`
   Parses and writes the existing XML mapping format.
2. `models.py`
   Small `slots=True` dataclasses for tiles, segments, controllers, scenes, and frames.
3. `patterns.py`
   Stateless pattern functions that return tile colors only.
4. `renderer.py`
   Owns precomputed controller routes and reusable `bytearray` payloads.
5. `engine.py`
   Separates output cadence from preview cadence and handles delta sending.
6. `output/ddp.py`
   Sends already-built payloads as DDP packets.
7. `presets.py`
   JSON preset persistence.
8. `benchmark.py`
   Simple measurable entry point for render throughput.

## Main performance choices

- Render tile colors first, not rich nested preview objects.
- Reuse controller payload buffers every frame.
- Precompute segment byte offsets once at startup.
- Keep the runtime pure-stdlib for the new core.
- Keep preview as a consumer of a compact frame snapshot, not as the center of the engine.
- Decouple preview timing from hardware output timing so UI cost cannot directly cap live output.
- Skip unchanged controller payloads while still sending periodic keepalives.

## What is intentionally not in phase 1

- Full Qt UI parity
- Full preview painter parity
- WLED discovery UI port
- Advanced transition compositing parity

Those belong in phase 2, after the faster runtime is proven and benchmarked.