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 codebase has compatibility seams for the named subsystems.
• The target subsystem extraction is still in progress, so these notes describe the architecture the implementation is moving toward, not a claim that every boundary is already pure.

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.

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 as extraction progress under later phases, especially eventing, the RuntimeHost split, render-thread ownership, persistence, backend lifecycle, and telemetry.