Hum Rahi

────────────────────────────────────────────────────────────
US-030.BE.1 — WebRTC Session Initiation & Signalling Server Logic
────────────────────────────────────────────────────────────

Role
As a backend developer on Ham Rahi,
I need to initiate and complete WebRTC signalling between the citizen
device and the assigned police panel operator the moment an SOS
activation event is received,
So that a one-way audio stream from Priya to ASI Akram is live within
3 seconds of activation, giving the operator real-time audio context
of the emergency environment.

User Story
As Priya,
I want the system to instantly connect my phone's microphone to the
police operator the moment my SOS activates,
So that the operator can hear what is happening around me even before
I am able to speak or type anything.

In-Scope

• Receiving and validating the SOS activation event from the frontend
  (interface boundary established in US-029.FE.1)
• Identifying and assigning the appropriate police panel operator
  session for the citizen's jurisdiction or duty zone
• Initiating the WebRTC signalling sequence: generating and delivering
  the SDP offer to the citizen device, receiving the SDP answer, and
  completing ICE candidate exchange with the police panel client
• Enforcing one-way audio only: citizen microphone stream flows to
  the police panel; no audio channel is opened from the police panel
  to the citizen device (receive-only for the operator in this story)
• Enforcing the 3-second establishment SLA from activation event
  receipt to confirmed audio stream active — the signalling server must
  complete offer/answer/ICE within this window under normal network
  conditions
• Generating and persisting an SOS session record at the moment of
  activation, including: citizen ID, timestamp, assigned operator,
  session ID, and activation GPS coordinates received alongside the
  activation event
• Handling the case where no operator is available in the assigned
  zone — fallback routing logic must be defined (e.g. next available
  operator, duty supervisor, or queue with timeout alert)
• Emitting a server-side event to the police panel to surface the
  incoming SOS and open the audio stream on the operator's interface
• Maintaining session state so the audio stream can be cleanly
  terminated by the operator when the incident is resolved

Out-of-Scope

• Two-way audio (operator-to-citizen audio is a Phase 2 upgrade
  restricted to operator authority; not in MVP)
• Video stream over WebRTC (separate story, Phase 2)
• TURN/STUN infrastructure provisioning (covered in US-030.INFRA.1)
• Citizen-side microphone access and stream capture (frontend story,
  not yet elaborated)
• Police panel UI rendering of the incoming SOS and audio controls
  (separate FE story under the police panel epic)
• SOS record display in the citizen dashboard (US-025/US-026 scope)
• Push notification to the citizen confirming connection (separate
  notification story)

Acceptance Criteria

AC1 On receipt of a valid SOS activation event, the signalling server
initiates a WebRTC SDP offer toward the citizen device within
500 ms of the event arriving at the backend.

AC2 The full signalling handshake — SDP offer, SDP answer, and ICE
candidate exchange — completes and the audio stream is confirmed
active within 3 seconds of the activation event timestamp, measured
server-side under standard network conditions (4G or better,
sub-100 ms RTT).

AC3 The audio stream is strictly one-way: only the citizen's microphone
audio is transmitted; the signalling configuration must not open
an audio send channel from the police panel to the citizen device.

AC4 An SOS session record is created in the database at the moment
of activation containing at minimum: citizen user ID, UTC
activation timestamp, assigned operator ID, WebRTC session ID,
and GPS coordinates from the activation payload.

AC5 If the primary assigned operator is unavailable (offline or at
capacity), the system applies the fallback routing rule and assigns
the next available operator within the duty zone; if no operator
is available within a defined timeout threshold, a supervisor alert
is raised and the session is queued.

AC6 The police panel receives a server-sent event or WebSocket push
notifying it of the incoming SOS and providing the session ID
required to join the audio stream, within the same 3-second
establishment window.

AC7 If the WebRTC handshake fails to complete within 3 seconds due
to signalling error, the backend logs the failure, marks the
session as degraded, and initiates a single automatic retry;
the retry attempt is also logged.

AC8 The signalling server correctly handles concurrent SOS activations
from multiple citizens without session ID collision or cross-stream
audio routing.

AC9 Session state is persisted such that a clean termination by the
operator (end-of-incident) closes the WebRTC stream, updates the
session record with a resolution timestamp, and releases server
resources without orphaned connections.

Definition of Done

• Signalling server initiates SDP offer within 500 ms confirmed by
  integration test
• End-to-end 3-second SLA met in integration test environment under
  simulated 4G conditions
• One-way audio constraint verified: no audio channel from operator
  to citizen in SDP negotiation
• SOS session record creation confirmed in DB with all required fields
• Fallback routing logic tested with primary operator marked offline
• Supervisor alert on zero-operator availability tested
• Concurrent SOS session test (minimum 5 simultaneous sessions)
  passing without cross-routing
• Operator termination flow tested and session record closed correctly
• No open P1 or P2 bugs
• Code reviewed and merged