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.

Status note:

• The Phase 1 design package is complete.
• The runtime implementation foothold is complete: the named runtime subsystems exist in code, RuntimeHost is retired from the compiled runtime path, and subsystem tests cover the new seams.
• The whole app is not fully extracted yet, so these notes still describe the architecture later phases should continue toward.

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-state facade over layer-stack, config, package-catalog, presentation, and persistence boundaries.
• RuntimeCoordinator.md Mutation validation, state classification, reset/reload policy, and publication/persistence requests.
• RuntimeSnapshotProvider.md Render-facing snapshot publication boundary backed by explicit render snapshot building/versioning.
• 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.

As of the current codebase, those design questions are settled well enough for later work to build against them. Remaining implementation work should be tracked under later phases, especially eventing, render-thread ownership, persistence, backend lifecycle, live-state layering, and telemetry.