# 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. Settlement rails

- Ethereum-compatible commitments mirror stream identity, manifests, and transport announcements.
- Observation consensus is a separate rail on top of those commitments: a reality-derived
  `ObservationHeader` is hashed, witnessed, and finalized per `(stream, epoch)` slot.
- The chain stores compact commitment pointers only; media bytes and full manifests remain on iroh,
  relays, and archive storage.
- OP Stack is the current private-chain operator target, with `ecp-forge` as the head node for the
  first Sepolia-anchored testnet tranche.
- Private-chain operation is a protocol extension, not a replacement for transport.

6. Relay mesh

- Relays cache objects and announce tracks.
- iroh provides programmable topology and peer routing.
- Multiple relays can serve identical objects.

7. 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.
- Witness: attests to a reality-derived observation hash for a stream epoch.

## 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.
- Observation consensus derives a second deterministic summary from the archive/manifests layer:
  `streamHash`, `epochHash`, `dataRoot`, and `locatorHash` become the on-chain observation header.
- Local manifests keep BLAKE3 `manifest_id`s and `merkle+blake3` proofs, while the Ethereum rail
  adds Keccak ABI/data commitments and optional secp256k1 EIP-712 body signatures for settlement.
- Discovery identity should prefer broadcast-scoped channel identity when available and only fall
  back to source-scoped IDs when the ingest path cannot yet prove a usable broadcast identity.
- PAT-derived identity is accepted only when the stream exposes a single non-zero program; ambiguous
  multi-program TS inputs remain source-scoped to avoid accidental convergence on the wrong channel.
- `ec-ts` parses ATSC PSIP at the table layer (`MGT`, `TVCT/CVCT`, `STT`, `RRT`, `EIT`, `ETT`),
  including `EIT` / `ETT` on the PIDs advertised by `MGT`.
- Current discovery promotion uses `PAT` plus `VCT` fields; the rest of PSIP is parsed and preserved
  for inspection, validation, and future policy rather than guessed into the stream key.

## Time synchronization

- Chunk boundaries are derived from PCR and, when available, broadcast UTC (ATSC STT / DVB TDT/TOT).
- ATSC STT is interpreted as GPS time plus offset correction, then converted to Unix time for chunk
  anchoring and diagnostics.
- Unsynced sources remain source-scoped until broadcast time is present.
- Discontinuities force a new chunk group boundary.