every.channel: sanitized baseline

docs/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Architecture
+
+## Layers
+
+1. Capture
+
+- Hardware: ATSC antennas -> HDHomeRun or Linux IPTV capture devices.
+- Output: MPEG-TS or ATSC 3.0 streams.
+
+2. Normalize
+
+- Demux and normalize timestamps.
+- Select program IDs and identify audio/video tracks.
+
+3. Deterministic transcode
+
+- Encode with a fixed profile (codec, GOP, bitrate, keyframe cadence).
+- Emit fixed-duration chunks with stable ordering.
+- Hash chunks to produce content identifiers.
+
+4. MoQ publish
+
+- Map each channel to a track namespace.
+- Each chunk becomes a MoQ object in a group.
+- Objects are named and addressed deterministically.
+
+5. Relay mesh
+
+- Relays cache objects and announce tracks.
+- iroh provides programmable topology and peer routing.
+- Multiple relays can serve identical objects.
+
+6. Playback
+
+- Desktop: Tauri app that subscribes to tracks.
+- CLI: debugging, inspection, and headless clients.
+- Web: static site that connects to a relay gateway.
+
+## Roles
+
+- Runner: owns capture + transcode + publish.
+- Chopper: executes deterministic chunking profiles.
+- Relay: stores and forwards MoQ objects.
+- Manager: configures nodes and applies policy.
+- Provisioner: bootstraps nodes and manages deployment.
+
+## Determinism
+
+- The same input with the same profile should yield identical chunks.
+- Chunk hashes are the primitive for availability and de-duplication.
+- Deterministic names allow relays to converge without coordination.
+
+## Time synchronization
+
+- Chunk boundaries are derived from PCR and, when available, broadcast UTC (ATSC STT / DVB TDT/TOT).
+- Unsynced sources remain source-scoped until broadcast time is present.
+- Discontinuities force a new chunk group boundary.