video-shader-toys/docs/subsystems

Phase 1 Subsystem Design Index

This directory contains the subsystem-specific design notes for Phase 1 of the architecture roadmap.

Start here if you want the Phase 1 package to read as one coherent deliverable rather than as separate subsystem writeups.

Parent documents:

• Architecture Resilience Review
• Phase 1: Subsystem Boundaries and Target Architecture

How This Set Fits Together

• PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md defines the top-level subsystem split, dependency rules, state categories, and migration guardrails.
• The notes in this directory expand each subsystem boundary without changing the parent Phase 1 design.
• The subsystem notes are meant to be read as design companions, not as independent alternate architectures.

Recommended Reading Order

1. PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md
2. RuntimeStore.md
3. RuntimeCoordinator.md
4. RuntimeSnapshotProvider.md
5. ControlServices.md
6. RenderEngine.md
7. VideoBackend.md
8. HealthTelemetry.md

That order mirrors the intended dependency story:

• durable state first
• mutation and publication next
• ingress and render boundaries after that
• device timing and operational visibility last

Subsystem Notes

• RuntimeStore.md Durable runtime config, persisted layer state, presets, and package metadata ownership.
• RuntimeCoordinator.md Mutation validation, state classification, reset/reload policy, and publication/persistence requests.
• RuntimeSnapshotProvider.md Render-facing snapshot build, publication, and versioning boundaries.
• ControlServices.md OSC, HTTP/WebSocket, and file-watch ingress plus normalization and service-local buffering.
• RenderEngine.md Sole-owner render/GL boundary, render-local transient state, preview, and playout-ready frame production.
• VideoBackend.md Device lifecycle, input/output pacing, buffer policy, and producer/consumer playout direction.
• HealthTelemetry.md Logs, warnings, counters, timing traces, and subsystem health snapshots.

What Phase 1 Should Settle

Phase 1 should leave the project with:

• one agreed subsystem vocabulary
• one agreed dependency direction map
• one agreed state-category model
• one agreed current-to-target migration story

Phase 1 does not need to settle every later implementation detail. The subsystem notes intentionally leave some questions open where later phases need room to choose concrete mechanics.