# Architecture

The normative target architecture is documented in `IMPLEMENTATION_PLAN.md`.
The current prototype separates the Qt GUI, worker process, CLI, and static core
library. The worker owns FFmpeg decode/export operations invoked by the GUI;
typed JSON documents are used at the process boundary. The core library owns
source identity, project/journal, navigation, preview transport, access-unit
inventory, GOP planning, and render-report models.

The current worker protocol still uses short-lived child processes and JSON on
standard output. Long-lived cancellable jobs, shared-memory preview transport,
worker restart/recovery, and the complete immutable source index remain target
architecture work rather than completed production facilities.

New FFmpeg-facing code uses the ownership types in `src/media/ffmpeg_raii.hpp`
for format, codec, packet, and frame lifetimes. Older executor paths are being
migrated incrementally and are not yet all RAII-backed.

GUI source loading obtains navigation identities from the worker's decoded
`video-frame-index-v2`; the UI does not independently infer frame count or
random-access safety from container packet flags.

Decoded indexes are cached per source fingerprint and video stream under the
user's local application-data directory. Cache envelopes include source
identity, schema version, and payload checksum; the source remains authoritative
and any failed validation causes an atomic rebuild.

Bounded decode/preview queues support stop-token cancellation and explicit
closure. Frame requests are translated from immutable display-frame identity to
indexed integer PTS before the decoder seeks to a prior random-access point and
decodes forward.

GUI playback starts a media worker that decodes the primary audio track and
reports Windows device position in integer microseconds. That device position
is the preview master clock; each progress update resolves to an indexed video
frame. A video-only timer is retained as a fallback for sources without usable
audio or systems without an available output device. Audio decode feeds at most
four prepared waveOut blocks, and pause requests graceful cancellation through
a per-session signal file with a two-second forced-termination safety fallback.
The versioned named-pipe control protocol remains the production target.
