Push Notification Delivery
Feature Detail
Description
Core push notification infrastructure enabling the app to send timely, role-aware alerts to peer mentors, coordinators, and org admins across iOS and Android. Notifications are triggered by system events (new assignments, status changes, approaching deadlines) and delivered via device-native channels with deep-link routing back to the relevant screen. Notifications must respect user accessibility settings, including VoiceOver/TalkBack compatibility and sufficient contrast in notification banners. Delivery is opt-in per category so users can manage notification fatigue without losing critical alerts. Unread count badges appear on the bottom nav Notifications tab.
Analysis
Reduces missed assignments and delayed follow-up, directly addressing the HLF finding that 40% of peer mentors felt insufficiently followed up. Keeps all parties informed without requiring manual check-ins.
Use Flutter local_notifications + FCM (Firebase Cloud Messaging) via Supabase Edge Functions. Store notification preferences per user in Supabase. Deep links handled via go_router. Test VoiceOver/TalkBack announcement of notification content.
Components (209)
Shared Components
These components are reused across multiple features
User Interface (59)
Service Layer (52)
Data Layer (33)
Infrastructure (54)
User Stories (24)
As a As a Peer Mentor (Likeperson)
I want to configure which types of notifications I receive and how (push, in-app, or both)
So that I can avoid notification fatigue while still being informed about the events that matter most to me
- Given a peer mentor opens notification preferences, when the screen loads, then all notification categories are listed with their current toggle states reflecting the saved preferences
- Given the user disables push notifications for 'Follow-up Reminders', when a reminder trigger fires, then no FCM push is sent but an in-app notification centre entry is still created
- Given the user disables all notifications for a category, when a trigger fires for that category, then neither a push nor an in-app notification is created for that user
- +2 more
As a As a Peer Mentor (Likeperson)
I want to receive a push notification confirming when my pause request has been approved by a coordinator
So that I have a clear record that my pause is active and I know my contacts will be handled during my absence
- Given a coordinator activates a pause for a peer mentor, when the pause record is saved, then a confirmation push notification is dispatched to the mentor within 60 seconds
- Given the confirmation notification is tapped, when the app opens, then the mentor is navigated to their status screen showing the pause start date, expected return date, and coordinator note if present
- Given a coordinator ends the mentor's pause ahead of schedule, when the status update is saved, then a 'Pause ended' push notification is dispatched to the mentor
- +2 more
As a As a Coordinator
I want to configure which types of notifications I receive and how (push, in-app, or both)
So that I can avoid notification fatigue while still being informed about the events that matter most to me
- Given a peer mentor opens notification preferences, when the screen loads, then all notification categories are listed with their current toggle states reflecting the saved preferences
- Given the user disables push notifications for 'Follow-up Reminders', when a reminder trigger fires, then no FCM push is sent but an in-app notification centre entry is still created
- Given the user disables all notifications for a category, when a trigger fires for that category, then neither a push nor an in-app notification is created for that user
- +2 more
As a As a Coordinator
I want to receive a push notification confirming when my pause request has been approved by a coordinator
So that I have a clear record that my pause is active and I know my contacts will be handled during my absence
- Given a coordinator activates a pause for a peer mentor, when the pause record is saved, then a confirmation push notification is dispatched to the mentor within 60 seconds
- Given the confirmation notification is tapped, when the app opens, then the mentor is navigated to their status screen showing the pause start date, expected return date, and coordinator note if present
- Given a coordinator ends the mentor's pause ahead of schedule, when the status update is saved, then a 'Pause ended' push notification is dispatched to the mentor
- +2 more
As a As a Organization Administrator
I want to configure which types of notifications I receive and how (push, in-app, or both)
So that I can avoid notification fatigue while still being informed about the events that matter most to me
- Given a peer mentor opens notification preferences, when the screen loads, then all notification categories are listed with their current toggle states reflecting the saved preferences
- Given the user disables push notifications for 'Follow-up Reminders', when a reminder trigger fires, then no FCM push is sent but an in-app notification centre entry is still created
- Given the user disables all notifications for a category, when a trigger fires for that category, then neither a push nor an in-app notification is created for that user
- +2 more
As a As a Organization Administrator
I want to receive a push notification confirming when my pause request has been approved by a coordinator
So that I have a clear record that my pause is active and I know my contacts will be handled during my absence
- Given a coordinator activates a pause for a peer mentor, when the pause record is saved, then a confirmation push notification is dispatched to the mentor within 60 seconds
- Given the confirmation notification is tapped, when the app opens, then the mentor is navigated to their status screen showing the pause start date, expected return date, and coordinator note if present
- Given a coordinator ends the mentor's pause ahead of schedule, when the status update is saved, then a 'Pause ended' push notification is dispatched to the mentor
- +2 more
As a As a Peer Mentor (Likeperson)
I want to see all my recent notifications in a dedicated notification centre screen with filtering and read/unread status
So that I can review missed notifications and take action on any I dismissed without opening the app in time
- Given a peer mentor opens the notification centre tab, when the screen loads, then all notifications for their account are listed in reverse chronological order
- Given there are unread notifications, when the user opens the notification centre, then unread items are visually distinguished (bold title, unread indicator dot)
- Given the user taps a notification list item, when navigation completes, then the notification is marked as read and the badge count on the bottom nav tab updates immediately
- +3 more
As a As a Peer Mentor (Likeperson)
I want to receive a push notification when my peer mentor certification is approaching its expiry date
So that I have enough time to enroll in a renewal course before my certification lapses and I am removed from the active mentor pool
- Given a peer mentor's certification expires in 30 days, when the nightly expiry check edge function runs, then a push notification is sent with the certification name and expiry date
- Given the push notification is tapped, when the app opens, then the user is navigated to the certification status screen showing the expiry date and renewal options
- Given the certification has already expired, when the evaluation runs, then the mentor's profile is flagged as inactive and suppressed from coordinator matching lists
- +2 more
As a As a Peer Mentor (Likeperson)
I want to be taken to the exact relevant screen when I tap any push notification
So that I can take immediate action without navigating manually through menus to find the relevant content
- Given a push notification with a contact deep link is tapped while the app is closed, when the app launches and authentication completes, then the contact detail screen for the specified contact is displayed
- Given a push notification is tapped while the app is in the background, when the app foregrounds, then the user is navigated to the linked screen without re-authenticating
- Given a notification deep link points to a coordinator-only screen, when a peer mentor taps it, then they are redirected to a role-appropriate fallback screen and shown an informational message
- +2 more
As a As a Peer Mentor (Likeperson)
I want to receive a push notification reminder when a contact has not been followed up within the configured time threshold
So that I do not forget about contacts who need attention and can maintain a consistent follow-up cadence
- Given an assignment has had no activity logged for 10 days, when the nightly scenario evaluation edge function runs, then a reminder push notification is dispatched to the assigned peer mentor
- Given the reminder notification is dispatched, when the mentor taps it, then they are deep-linked directly to the relevant contact detail screen
- Given a reminder was sent for an assignment today, when the evaluation runs again within the cooldown window (e.g., 3 days), then no duplicate reminder is sent for the same assignment
- +2 more
As a As a Coordinator
I want to see all my recent notifications in a dedicated notification centre screen with filtering and read/unread status
So that I can review missed notifications and take action on any I dismissed without opening the app in time
- Given a peer mentor opens the notification centre tab, when the screen loads, then all notifications for their account are listed in reverse chronological order
- Given there are unread notifications, when the user opens the notification centre, then unread items are visually distinguished (bold title, unread indicator dot)
- Given the user taps a notification list item, when navigation completes, then the notification is marked as read and the badge count on the bottom nav tab updates immediately
- +3 more
As a As a Coordinator
I want to receive a push notification when my peer mentor certification is approaching its expiry date
So that I have enough time to enroll in a renewal course before my certification lapses and I am removed from the active mentor pool
- Given a peer mentor's certification expires in 30 days, when the nightly expiry check edge function runs, then a push notification is sent with the certification name and expiry date
- Given the push notification is tapped, when the app opens, then the user is navigated to the certification status screen showing the expiry date and renewal options
- Given the certification has already expired, when the evaluation runs, then the mentor's profile is flagged as inactive and suppressed from coordinator matching lists
- +2 more
As a As a Coordinator
I want to be taken to the exact relevant screen when I tap any push notification
So that I can take immediate action without navigating manually through menus to find the relevant content
- Given a push notification with a contact deep link is tapped while the app is closed, when the app launches and authentication completes, then the contact detail screen for the specified contact is displayed
- Given a push notification is tapped while the app is in the background, when the app foregrounds, then the user is navigated to the linked screen without re-authenticating
- Given a notification deep link points to a coordinator-only screen, when a peer mentor taps it, then they are redirected to a role-appropriate fallback screen and shown an informational message
- +2 more
As a As a Coordinator
I want to receive a push notification reminder when a contact has not been followed up within the configured time threshold
So that I do not forget about contacts who need attention and can maintain a consistent follow-up cadence
- Given an assignment has had no activity logged for 10 days, when the nightly scenario evaluation edge function runs, then a reminder push notification is dispatched to the assigned peer mentor
- Given the reminder notification is dispatched, when the mentor taps it, then they are deep-linked directly to the relevant contact detail screen
- Given a reminder was sent for an assignment today, when the evaluation runs again within the cooldown window (e.g., 3 days), then no duplicate reminder is sent for the same assignment
- +2 more
As a As a Organization Administrator
I want to see all my recent notifications in a dedicated notification centre screen with filtering and read/unread status
So that I can review missed notifications and take action on any I dismissed without opening the app in time
- Given a peer mentor opens the notification centre tab, when the screen loads, then all notifications for their account are listed in reverse chronological order
- Given there are unread notifications, when the user opens the notification centre, then unread items are visually distinguished (bold title, unread indicator dot)
- Given the user taps a notification list item, when navigation completes, then the notification is marked as read and the badge count on the bottom nav tab updates immediately
- +3 more
As a As a Organization Administrator
I want to receive a push notification when my peer mentor certification is approaching its expiry date
So that I have enough time to enroll in a renewal course before my certification lapses and I am removed from the active mentor pool
- Given a peer mentor's certification expires in 30 days, when the nightly expiry check edge function runs, then a push notification is sent with the certification name and expiry date
- Given the push notification is tapped, when the app opens, then the user is navigated to the certification status screen showing the expiry date and renewal options
- Given the certification has already expired, when the evaluation runs, then the mentor's profile is flagged as inactive and suppressed from coordinator matching lists
- +2 more
As a As a Organization Administrator
I want to be taken to the exact relevant screen when I tap any push notification
So that I can take immediate action without navigating manually through menus to find the relevant content
- Given a push notification with a contact deep link is tapped while the app is closed, when the app launches and authentication completes, then the contact detail screen for the specified contact is displayed
- Given a push notification is tapped while the app is in the background, when the app foregrounds, then the user is navigated to the linked screen without re-authenticating
- Given a notification deep link points to a coordinator-only screen, when a peer mentor taps it, then they are redirected to a role-appropriate fallback screen and shown an informational message
- +2 more
As a As a Organization Administrator
I want to receive a push notification reminder when a contact has not been followed up within the configured time threshold
So that I do not forget about contacts who need attention and can maintain a consistent follow-up cadence
- Given an assignment has had no activity logged for 10 days, when the nightly scenario evaluation edge function runs, then a reminder push notification is dispatched to the assigned peer mentor
- Given the reminder notification is dispatched, when the mentor taps it, then they are deep-linked directly to the relevant contact detail screen
- Given a reminder was sent for an assignment today, when the evaluation runs again within the cooldown window (e.g., 3 days), then no duplicate reminder is sent for the same assignment
- +2 more
As a As a Peer Mentor (Likeperson)
I want to be prompted to grant push notification permissions during onboarding with a clear explanation of why they are needed
So that I understand the value of enabling notifications and can make an informed decision without feeling pressured
- Given a peer mentor completes initial login, when they reach the onboarding step that explains notifications, then the OS permission dialog is shown with a contextual pre-prompt message explaining the benefit
- Given the user grants notification permission, when the FCM token is generated, then the token is stored in the backend linked to the user's profile within 5 seconds
- Given the user denies notification permission, when they navigate to notification settings in the app, then a button is displayed that opens the OS system settings to allow them to re-enable notifications
- +2 more
As a As a Peer Mentor (Likeperson)
I want to receive a push notification immediately when I am assigned a new contact or follow-up task
So that I can respond promptly without having to manually check the app for updates
- Given a coordinator assigns a new contact to a peer mentor, when the assignment is saved in the database, then an FCM push notification is dispatched to the mentor's registered device within 30 seconds
- Given the peer mentor taps the notification, when the app opens, then the user is navigated directly to the assignment or contact detail screen via the deep link
- Given the app is in the foreground when the notification arrives, when the notification is received, then an in-app banner is displayed without interrupting the current workflow
- +2 more
As a As a Coordinator
I want to be prompted to grant push notification permissions during onboarding with a clear explanation of why they are needed
So that I understand the value of enabling notifications and can make an informed decision without feeling pressured
- Given a peer mentor completes initial login, when they reach the onboarding step that explains notifications, then the OS permission dialog is shown with a contextual pre-prompt message explaining the benefit
- Given the user grants notification permission, when the FCM token is generated, then the token is stored in the backend linked to the user's profile within 5 seconds
- Given the user denies notification permission, when they navigate to notification settings in the app, then a button is displayed that opens the OS system settings to allow them to re-enable notifications
- +2 more
As a As a Coordinator
I want to receive a push notification immediately when I am assigned a new contact or follow-up task
So that I can respond promptly without having to manually check the app for updates
- Given a coordinator assigns a new contact to a peer mentor, when the assignment is saved in the database, then an FCM push notification is dispatched to the mentor's registered device within 30 seconds
- Given the peer mentor taps the notification, when the app opens, then the user is navigated directly to the assignment or contact detail screen via the deep link
- Given the app is in the foreground when the notification arrives, when the notification is received, then an in-app banner is displayed without interrupting the current workflow
- +2 more
As a As a Organization Administrator
I want to be prompted to grant push notification permissions during onboarding with a clear explanation of why they are needed
So that I understand the value of enabling notifications and can make an informed decision without feeling pressured
- Given a peer mentor completes initial login, when they reach the onboarding step that explains notifications, then the OS permission dialog is shown with a contextual pre-prompt message explaining the benefit
- Given the user grants notification permission, when the FCM token is generated, then the token is stored in the backend linked to the user's profile within 5 seconds
- Given the user denies notification permission, when they navigate to notification settings in the app, then a button is displayed that opens the OS system settings to allow them to re-enable notifications
- +2 more
As a As a Organization Administrator
I want to receive a push notification immediately when I am assigned a new contact or follow-up task
So that I can respond promptly without having to manually check the app for updates
- Given a coordinator assigns a new contact to a peer mentor, when the assignment is saved in the database, then an FCM push notification is dispatched to the mentor's registered device within 30 seconds
- Given the peer mentor taps the notification, when the app opens, then the user is navigated directly to the assignment or contact detail screen via the deep link
- Given the app is in the foreground when the notification arrives, when the notification is received, then an in-app banner is displayed without interrupting the current workflow
- +2 more