🏠 Overview › 👥 User Roles ›📖 Navigate Directly to a Specific Screen via Push No...

Navigate Directly to a Specific Screen via Push Notification Deep Link

The App Router Service is configured with go_router deep link support. When the app receives a push notification tap event, the notification payload contains a target route path. The App Router Service resolves this path, sets the appropriate active tab in the Navigation State Store, and navigates to the target screen — pushing it onto the correct tab's navigator stack so the user can still tap Back to return to the tab root. If the app is in the background or terminated, deep link navigation occurs after the authentication state is confirmed.

HIGH story-navigation-shell-organization-administrator-005 5 pts
5
Story Points
High
Priority
Navigation Shell
Feature

User Story

As a user
I want tapping a push notification to bring me directly to the relevant screen in the app (e.g., a new assignment, an approval request, or an expiry alert) without manually navigating through the tab structure
So that So that I can act on time-sensitive information immediately and reduce the steps needed to respond

Acceptance Criteria

  • Given a peer mentor receives a push notification for a new encrypted assignment, when they tap the notification, then the app opens to the Assignment Detail screen with the correct assignment loaded
  • Given a coordinator receives a notification about a pending reimbursement approval, when they tap the notification, then the app navigates to the Reimbursement Detail screen within the Work tab
  • Given the app is terminated, when the user taps a push notification, then the app launches, authenticates the user, and then navigates to the deep link destination
  • Given the deep link destination requires a permission the current user does not have, when the deep link is resolved, then the user is shown the No-Access screen rather than an unhandled error
  • Given the user has navigated to a deep link destination, when they press the Back button, then they return to the root of the tab that contains the deep link destination

Business Value

Deep link navigation from push notifications reduces the friction of responding to time-sensitive events — unacknowledged assignments, pending approvals, and expiring certificates. This is directly tied to the HLF finding that 40% of peer mentors felt insufficiently followed up by coordinators. Eliminating navigation friction from notifications increases response rates and closes the feedback loop faster, improving both volunteer engagement and operational reliability.

Components

Navigation Shell
Related Feature
Organization Administrator
User Role