Context
Live-stream behavior in content detail had grown into UI-coupled logic spread across settings handlers and state updates.
This created recurring problems:
- Business rules mixed with UI lifecycle concerns
- Inconsistent handling of provider-specific states and transitions
- Difficult parity verification across happy/sad/edge scenarios
- Higher risk when backend payload shape evolves (especially GraphQL-first fields and nullability)
A decision was needed on where live-stream decisioning should live so that UI remains a thin adapter and runtime behavior stays testable and stable.
Decision
Adopt a dedicated internal Live Stream Runtime as the architectural boundary and becomes the single source of truth for live-stream state derivation and operational decisioning.
The runtime owns provider resolution, protocol URL derivation, UI-flag derivation, transition rules, action request construction, and polling orchestration behind a single contract.
UI and context layers consume this contract strictly as adapters and must not implement live-stream business rules.
The runtime contract is aligned to current GraphQL domain shape and nullability expectations.
Consequences
-
Enables
- Deterministic live-stream behavior independent of UI rendering concerns
- High-confidence characterization and unit testing for parity-sensitive flows
- Safer backend evolution by localizing payload-shape handling to runtime boundary
- Simplifies future real-time enhancements (e.g., polling infrastructure) by keeping state derivation centralized
-
Restricts
- New live-stream rules must be added in runtime modules, not directly in page-level UI handlers
- Provider-specific behavior must follow shared runtime contract semantics
-
Trade-offs accepted
- Added internal module surface and contract maintenance overhead
- Initial migration effort to move logic out of legacy UI-coupled paths
Notes
UI wiring and final provider-specific GraphQL call-shape updates are implementation concerns that follow this ADR and do not change the decision itself.