Hum Rahi

────────────────────────────────────────────────────────────
US-031.BE.1 — Location Payload Ingestion, Persistence & Real-Time
Broadcast to Police Panel
────────────────────────────────────────────────────────────

Role
As a backend developer on Ham Rahi,
I need to receive the citizen's GPS location payloads every 5 seconds,
persist each fix to the SOS session record, and immediately broadcast
the latest position to the assigned police panel operator in real time,
So that ASI Akram always sees Priya's current location on the panel
map with no manual refresh and no perceptible lag.

User Story
As ASI Akram,
I want the citizen's location to appear on my panel and update
automatically every 5 seconds throughout the SOS session,
So that I can track their movement in real time and dispatch the
correct response unit to their actual position.

In-Scope

• Exposing a location ingestion endpoint that accepts authenticated
  location payloads from the citizen device for a given active
  session ID
• Validating each incoming payload: session ID must correspond to
  an active SOS session; payloads for unknown, expired, or closed
  sessions are rejected and logged
• Persisting each validated location fix to the SOS session location
  log with: latitude, longitude, accuracy radius, device timestamp,
  server receipt timestamp, staleness flag, and session ID
• Broadcasting each validated fix to the assigned police panel
  operator via the existing WebSocket or server-sent event channel
  established in US-030.BE.1, within 1 second of server receipt
• Handling the staleness flag: broadcasting stale fixes to the panel
  with the staleness indicator intact so the operator UI can surface
  a location-lag warning
• Handling the permission-denied null payload: broadcasting the
  null payload to the panel with the permission-denied flag so the
  operator is informed that location is unavailable rather than
  assuming the citizen is stationary
• Handling missed transmissions: if no payload is received from a
  device within 15 seconds (three missed cycles), raising a
  location-loss event on the session and notifying the panel
• Stopping ingestion and broadcast cleanly when the session is
  terminated; no further payloads are accepted or broadcast after
  session close
• Ensuring location log data is associated with the SOS incident
  record and retained in accordance with the data retention policy
  agreed with Bhopal Police

Out-of-Scope

• Police panel map rendering or UI (separate FE story)
• Route reconstruction or location history playback (Phase 2)
• Geofencing, proximity calculation, or nearest unit dispatch logic
  (Phase 2)
• Location data sharing with third parties or external GIS systems
  (Phase 2)
• Citizen-facing location confirmation UI
• STUN/TURN or WebRTC media infrastructure (US-030.INFRA.1)

Acceptance Criteria

AC1 The location ingestion endpoint accepts authenticated payloads
only for session IDs that correspond to an active SOS session;
payloads referencing unknown, closed, or expired sessions are
rejected with a 4xx response and the rejection is logged.

AC2 Each valid incoming location fix is persisted to the session
location log with all required fields: latitude, longitude,
accuracy radius, device timestamp, server receipt timestamp,
staleness flag, and session ID.

AC3 Each validated fix is broadcast to the assigned police panel
operator via the real-time channel within 1 second of server
receipt under normal load conditions.

AC4 Stale fixes (staleness flag set by the device) are persisted
and broadcast with the staleness indicator intact; the panel
receives the flag and the fix age in seconds.

AC5 Null payloads carrying a permission-denied flag are persisted
and broadcast to the panel with the flag intact; the backend
does not treat a null-location payload as a transmission error.

AC6 If no location payload is received from the citizen device
within 15 seconds of the last successful receipt, the backend
raises a location-loss event on the session and pushes a
location-unavailable notification to the assigned panel operator.

AC7 Location ingestion and broadcast cease within one processing
cycle of session termination; payloads arriving after session
close are rejected and logged.

AC8 The location log for a closed session is retained and
associated with the SOS incident record in accordance with
the agreed data retention policy; it is accessible to
authorised administrators for audit purposes.

AC9 Under a load test simulating the peak concurrent SOS session
count defined in the Ham Rahi capacity model, the broadcast
latency from server receipt to panel delivery remains within
1 second for at least 95% of location events.

Definition of Done

• Ingestion endpoint rejecting invalid/closed session IDs confirmed
  by integration test
• All required fields persisted to location log confirmed by DB
  inspection in test
• 1-second broadcast latency to panel confirmed in integration test
• Staleness flag round-trip (device → backend → panel) confirmed
• Permission-denied null payload handling confirmed
• 15-second location-loss event and panel notification confirmed
  by simulating device silence mid-session
• Post-session-close rejection of late payloads confirmed
• Data retention association with incident record confirmed
• Load test at peak concurrency meeting AC9 threshold
• No open P1 or P2 bugs
• Code reviewed and merged