# Subsystem Notes Index

The current, phase-free architecture summary is:

- [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md)

Start there when you want to understand how the application works now.

This directory contains deeper notes for individual subsystem boundaries. These notes were originally written during the phased architecture work, so some files may still mention migration steps or target-state language. Treat them as companion notes, not as the source of truth when they disagree with the current architecture summary.

## Recommended Reading Order

1. [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md)
2. [RuntimeStore](RuntimeStore.md)
3. [RuntimeCoordinator](RuntimeCoordinator.md)
4. [RuntimeSnapshotProvider](RuntimeSnapshotProvider.md)
5. [ControlServices](ControlServices.md)
6. [RenderEngine](RenderEngine.md)
7. [VideoBackend](VideoBackend.md)
8. [HealthTelemetry](HealthTelemetry.md)

That order follows the current ownership story:

- durable state first
- mutation and publication next
- control ingress after that
- render ownership and video timing next
- operational visibility last

## Subsystem Notes

- [RuntimeStore](RuntimeStore.md): durable runtime-state facade over layer-stack, config, package-catalog, presentation, and persistence boundaries.
- [RuntimeCoordinator](RuntimeCoordinator.md): mutation validation, state classification, reset/reload policy, and publication/persistence requests.
- [RuntimeSnapshotProvider](RuntimeSnapshotProvider.md): render-facing snapshot publication boundary backed by explicit render snapshot building/versioning.
- [ControlServices](ControlServices.md): OSC, HTTP/WebSocket, and file-watch ingress plus normalization and service-local buffering.
- [RenderEngine](RenderEngine.md): GL ownership boundary, render-local transient state, preview, and playout-ready frame production.
- [VideoBackend](VideoBackend.md): device lifecycle, input/output pacing, buffer policy, and producer/consumer playout behavior.
- [HealthTelemetry](HealthTelemetry.md): logs, warnings, counters, timing traces, and subsystem health snapshots.

## Historical Documents

The `docs/PHASE_*` files and experiment logs record how the architecture evolved. They are useful when you need rationale, investigation history, or rejected paths, but they are no longer arranged as the main feature split for the app.

For current implementation work, use [Current System Architecture](../CURRENT_SYSTEM_ARCHITECTURE.md) as the entry point and only dip into the phase documents when you need context for why a subsystem ended up this way.
