Hum Rahi

US-031.FE.1 — Citizen Device GPS Capture & Continuous Location Transmission

Role
As a frontend developer on Ham Rahi,
I need to acquire the citizen's GPS coordinates on the device and
transmit them to the backend every 5 seconds for the duration of an
active SOS session,
So that the police panel always has a current, accurate position for
Priya without any manual input from her.

User Story
As Priya,
I want my phone to automatically and continuously share my live
location with the police operator from the moment my SOS activates
until the session ends,
So that help can be directed to wherever I am, even if I am moving
or unable to communicate.

In-Scope

• Requesting device location permission at app install or first SOS
  screen visit if not already granted; SOS activation must not be
  blocked by a permission prompt at the moment of emergency
• Acquiring GPS coordinates from the device location API at the
  moment of SOS activation for the initial position fix sent with
  the activation event (interface with US-030.BE.1)
• Starting a repeating location acquisition cycle immediately after
  activation, capturing a fresh coordinate pair every 5 seconds
• Transmitting each coordinate pair — latitude, longitude, accuracy
  radius, and device timestamp — to the backend location endpoint
  within the same 5-second cycle
• Continuing transmission for the full duration of the active SOS
  session; transmission stops only when the session is terminated
  server-side or the app receives a session-end signal
• Handling GPS signal degradation gracefully: if a fresh fix cannot
  be obtained within the 5-second window, transmit the last known
  valid coordinates with a staleness flag indicating the fix age
• Handling the case where location permission is denied: surfacing a
  non-blocking warning to the user and transmitting a null location
  payload with a permission-denied flag so the backend and panel
  are informed rather than left waiting
• Continuing location transmission if the app moves to the background
  during an active SOS session, using background location access where
  the OS permits it
• Stopping all location acquisition and transmission cleanly when the
  session-end signal is received; no location data is transmitted
  after session close

Out-of-Scope

• Rendering the live map or location on the citizen's own screen
  (separate FE story)
• Police panel map rendering (separate FE story under the panel epic)
• Location history storage or playback (Phase 2)
• Geofencing or proximity alerts (Phase 2)
• Location sharing outside of an active SOS session
• Network retry logic for failed transmissions (covered in BE.1)

Acceptance Criteria

AC1 Location permission is requested proactively before the SOS
screen is first accessed; the SOS activation flow is not
interrupted by a permission dialog at the moment of emergency.

AC2 The initial GPS fix is captured and included in the SOS
activation payload sent to US-030.BE.1 at the moment of
activation.

AC3 Following activation, a fresh GPS fix is acquired and transmitted
to the backend location endpoint every 5 seconds (±500 ms
tolerance) without requiring any action from the citizen.

AC4 Each transmitted location payload includes: latitude, longitude,
accuracy radius in metres, device-local timestamp, and session ID.

AC5 If a fresh GPS fix is unavailable within the 5-second window,
the last valid fix is transmitted with a staleness flag and the
age of that fix in seconds.

AC6 If location permission is denied, a non-blocking in-screen
warning is shown to the citizen and a null location payload with
a permission-denied flag is transmitted to the backend each cycle
so the operator knows location is unavailable.

AC7 Location transmission continues uninterrupted if the app is
backgrounded during an active session, subject to OS background
location permissions; any OS-imposed restriction on background
location is logged and surfaced via the staleness flag.

AC8 On receipt of a session-end signal from the backend, location
acquisition stops within one cycle (≤5 seconds) and no further
payloads are transmitted.

AC9 No location data is transmitted before SOS activation or after
session termination.

Definition of Done

• Permission pre-request flow tested on Android and iOS before
  SOS screen access
• 5-second transmission cycle verified by QA with packet-level
  timing confirmation
• Staleness flag transmission confirmed via GPS signal simulation
  (airplane mode mid-session test)
• Permission-denied path tested: warning displayed and null payload
  transmitted
• Background location transmission confirmed on physical Android and
  iOS devices
• Clean stop on session-end signal confirmed with no post-close
  transmissions
• No open P1 or P2 bugs
• Code reviewed and merged