Hum Rahi

📖 Story¶

As Rahul (a citizen), I want to receive a push notification on my phone when the status of my submitted report changes, so that I am informed of progress without having to open the app to check manually.

🎯 Goal & Context¶

After submitting a report, citizens have no visibility into what happens next unless they actively return to the app. This creates anxiety and erodes trust in the platform. Push notifications close that feedback loop passively — the citizen is informed at the moment something meaningful changes, without any effort on their part.

This feature spans three layers: the backend must detect and trigger the notification event, the infrastructure layer must deliver it reliably across platforms, and the frontend must handle the notification tap and route the user correctly.

✅ In-Scope¶

• Push notification triggered when a report status changes to Assigned or Resolved
• Notification delivered to the citizen who submitted the report
• Tapping the notification opens the app and navigates directly to that report's detail screen
• Opt-in permission request flow on first launch (iOS and Android)
• Notification permission state respected — no silent failures surfaced to the user
• Device token registration and management

❌ Out-of-Scope¶

• Notifications for status changes other than Assigned and Resolved (e.g., Submitted → Assigned intermediate states are not separately notified unless scoped in)
• Email or SMS notification (separate story)
• In-app notification centre / inbox (separate story)
• Bulk or broadcast notifications to all citizens
• Admin-triggered manual notifications

📣 Notification Content Spec¶

Rules:

• [Report Title] must be dynamically injected — never send a generic notification
• Title and body must not exceed platform character limits (iOS: ~50 chars title / ~100 chars body visible in lock screen)
• Long report titles must be truncated gracefully with ellipsis — do not let them break the notification layout
• Notifications must be sent in the language preference set on the citizen's profile (if multi-language is in scope for this sprint — confirm with PM)

🔔 Notification Behaviour by Platform¶

📱 Permission Request Flow¶

• Do not ask for notification permission immediately on first app launch — this is a known pattern that leads to high denial rates
• Trigger the permission prompt after a citizen successfully submits their first report, with a contextual explanation: "Allow notifications so we can keep you updated when your report status changes."
• If the citizen denies, do not ask again in the same session
• If the citizen denies at OS level, surface a soft prompt on the My Reports screen: "Enable notifications to get status updates" with a link to device settings — shown once per 30 days maximum
• Permission state (granted / denied / not-asked) must be stored and respected at all times

⚙️ System Behaviour & Business Rules¶

• A notification must be sent once per status transition — duplicate notifications for the same status change on the same report are not acceptable
• If a report changes status multiple times rapidly (e.g., Assigned → Resolved within seconds), each transition triggers its own notification independently
• Notifications must only be sent to the report owner — never to other citizens
• If the citizen has multiple devices, the notification should be delivered to all registered active devices
• A device token that has been inactive for more than 90 days should be considered stale — define cleanup policy with the Infra team
• Notification delivery is best-effort — a failed delivery should not block or roll back the status change on the backend

🗺️ Deep Link & Navigation Behaviour¶

❗ Error Handling¶

📏 Acceptance Criteria¶

🔗 Dependencies & Open Questions¶

✅ Definition of Done¶

• All 10 ACs pass QA sign-off on both iOS and Android
• Notification content reviewed and approved by PM before deployment
• No duplicate notification delivered for any tested status transition
• Deep link navigation tested for all app states (foreground, background, closed)
• Permission denial scenario tested — confirmed no notification sent and no crash
• Stale token cleanup policy documented and agreed with Infra
• Notification delivery failures logged and observable in monitoring dashboard
• Load tested: notification dispatch does not degrade status-update API response time