Final-Year-Project/docs/STREAMING_SIMPLIFICATION_IMPLEMENTATION_PLAN.md

Implementation Plan: Streaming Simplification (WebRTC-only)

0) Goal and scope

Goal

Simplify the current streaming architecture to a single production-pragmatic implementation path:

• Control plane via REST + socket signaling
• Media plane via WebRTC only
• No JPEG frame fallback relay
• Preserve security and device-role authorization

Scope in/out

• In scope:
  • Stream request/accept/end lifecycle
  • Device role and ownership checks
  • WebRTC signaling and connection setup/teardown
  • Frontend Web + Mobile stream runtime paths
  • API/docs updates for simplified contract
• Out of scope:
  • Multi-party broadcast or conferencing
  • SFU/ingest pipeline replacement in this phase
  • Media provider feature parity with mock provider URLs
  • Full recording workflow and upload/finalization

1) Current-state constraints to keep

• Devices use bearer tokens and role-based socket/session authentication.
• Stream request is initiated by a client device targeting a linked camera.
• Current schema/event names exist and are used across components.
• Backend and frontends already support stream:requested, stream:started, stream:ended, and webrtc:signal.

2) Explicit requirements

1. Runtime complexity reduction:
   • Keep one media transport: WebRTC.
   • Remove socket JPEG fallback flow from runtime.
2. Reliability and safety:
   • Keep strict owner/role checks for all stream/session endpoints.
   • Ensure deterministic teardown when stream ends.
3. Maintainability:
   • Remove dead or non-critical branches.
   • Minimize special-case flags and dual state machines.
4. Backward compatibility strategy:
   • Prefer a feature flag SIMPLE_STREAMING for controlled rollout.

3) Assumptions

• Existing database schema can remain (deprecating fields is acceptable for now).
• Camera and client are expected to be online for primary WebRTC path; if not reachable, stream request/accept will fail gracefully.
• stream:frame is not required for core user value in phase 1.
• Recording features can be delayed or gated without blocking stream acceptance.
• Existing command dispatch infrastructure can be simplified or replaced by direct request/session events without redesigning auth.

4) Non-goals and excluded behaviors

• No immediate migration to true production-grade media server or SFU.
• No auto-retry queue for offline command delivery.
• No new codec/transcoding pipeline.

5) Target architecture

Backend

• Stream endpoints: request -> accept -> end.
• Session state transitions:
  • requested -> streaming -> ended
• Commands table may be retained only for audit/logging or removed later.
• Gateway relays:
  • webrtc:signal only for media negotiation.
  • stream:started and stream:ended for lifecycle updates.

Frontend (Web + Mobile)

• Shared runtime model:
  • idle -> connecting -> active -> ended
• On camera accept: start WebRTC offer.
• On client started event: start WebRTC answer/handling.
• On ended: stop peer connections, clear state.
• No frame image fallback state/UI.

6) Phased implementation strategy

Phase 1: Contract freeze and safety gate (Day 0)

1. Lock simplified state contract and event matrix.
2. Add/validate SIMPLE_STREAMING flag and default behavior.
3. Add migration notes for legacy paths.

Phase 2: Backend control-plane simplification (Day 1)

1. Refactor stream request/accept/end handlers to only manage session lifecycle and signaling.
2. Remove/disable stream-provider-specific runtime side effects from these handlers.
3. Ensure response payloads are minimal and stable.

Phase 3: Gateway simplification (Day 1)

1. Remove stream:frame event handler and related relay state.
2. Keep only validated WebRTC signaling and lifecycle event emitters.
3. Remove command retry loop if not required by flag.

Phase 4: Web frontend simplification (Day 2)

1. Simplify stream controller into single mode.
2. Remove image fallback flow and related timers/state.
3. Keep single video render path and deterministic cleanup.

Phase 5: Mobile frontend simplification (Day 2)

1. Remove periodic frame capture/relay code and image fallback rendering.
2. Keep camera capture + WebRTC publish path.
3. Align end/cleanup behavior with web.

Phase 6: API/doc/ops cleanup (Day 3)

1. Update OpenAPI/event docs and internal docs.
2. Deprecate references to frame-based streaming and mock endpoints in code comments.
3. Add rollout and rollback runbook.

Phase 7: Validation and rollout (Day 4)

1. Manual runtime smoke tests for request/accept/offer/answer/end.
2. Validate unauthorized access rejection for all endpoints.
3. Rollout in flag-off/flag-on modes and monitor.

7) Sequence and dependency reasoning

• Backend simplification must land before frontend simplification to avoid client calling removed paths.
• Gateway simplification is independent after stream endpoints are stable but should be merged before frontend hardening.
• Frontend changes rely on a stable event contract (webrtc:signal, stream:started, stream:ended).
• Docs/validation are final tasks once behavior stabilizes.

8) Failure handling and risk controls

1. Rollback strategy: feature flag switch routes behavior back to existing legacy logic.
2. Forward progress gate: stream accept/start should not require any media provider credential.
3. Safety gate: reject unknown/non-matching event payloads in gateway before forwarding.
4. Error handling: explicit peer connection cleanup on timeout/error and session end.
5. Observability: structured logs for request/accept/offer/answer/hangup/end with stream session ids.

9) Acceptance criteria

1. client -> request -> camera accept -> live WebRTC stream works on web and mobile.
2. No stream:frame event is used in runtime media path.
3. Stream teardown always emits stream:ended, clears peer connections, and stops capture.
4. Unauthorized role/device combinations are rejected with explicit errors.
5. OpenAPI and internal docs only advertise simplified contract by default.
6. Feature flag allows toggling between simplified and legacy behavior for quick rollback.