RFP_Infinity-Vis/Infinity_Vis_1/ARCHITECTURE.md

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.