Push Notifications & Scenario-Based Alerts
Feature Detail
Description
This feature delivers a comprehensive push notification system that keeps peer mentors and coordinators informed through timely, context-aware alerts. It supports scenario-based messaging triggered by specific events such as new assignments, upcoming deadlines, follow-up reminders, and activity milestones. The system also provides calendar synchronization so that scheduled activities and events appear in the user's native device calendar, reducing the risk of missed engagements and improving overall follow-through on commitments.
Analysis
Push notifications are essential for maintaining engagement among a volunteer peer mentor base that does not log into the app daily. HLF's survey found 40% of peer mentors were dissatisfied with follow-up, and scenario-based push messages directly address this gap by automating timely outreach without coordinator effort. Calendar sync reduces no-shows for scheduled activities, improving service quality for end users. Together these capabilities transform the app from a passive logging tool into an active engagement platform, increasing retention, reducing coordinator administrative burden, and ultimately delivering more consistent support to the people the organizations serve.
Implement using Firebase Cloud Messaging (FCM) for Android and APNs for iOS, wrapped through a Supabase Edge Function trigger layer so that database events (new assignment, approaching deadline, inactivity threshold) automatically enqueue notifications. The Flutter client uses the firebase_messaging package with foreground, background, and terminated state handlers. Notification settings screen allows per-category opt-in/opt-out stored in push_notification_configs. Calendar sync uses the device_calendar Flutter plugin to write events to the native calendar with appropriate permissions. Scenario logic is defined server-side as configurable rules, enabling organizations to customize trigger conditions without app updates.
Dependencies
Definition of Done
User Stories (21)
As a As a user
I want I want to mark individual notifications as read by tapping them, mark all notifications as read with a single action, and delete individual notifications by swiping them away
So that So that I can maintain a clean, actionable notification list that accurately reflects which items still require my attention
- Given a user taps an unread notification item, when the tap is processed, then the notification is marked as read in the database and the unread indicator is removed from that item
- Given a user swipes a notification item to the left, when the swipe reaches the delete threshold, then a delete confirmation action is revealed; when confirmed, the notification is deleted from the database and removed from the list
- Given a user taps 'Mark all as read', when the action is confirmed, then all notifications in the list are updated to read status in a single batch operation and all unread indicators are removed
- +2 more
As a As a user
I want I want tapping a push notification to open the app and navigate me directly to the specific screen relevant to that notification, without requiring me to manually navigate from the home screen
So that So that I can act on notifications immediately with the minimum number of steps, especially on mobile where navigating through multiple screens is slow and error-prone
- Given a user taps a 'new assignment' push notification while the app is terminated, when the app launches, then after successful authentication verification the user is navigated to the Assignment Detail screen for that specific assignment
- Given a user taps a push notification while the app is backgrounded, when the app comes to foreground, then the user is navigated to the target screen without passing through the home screen
- Given the target entity no longer exists when the notification is tapped (e.g., assignment was withdrawn), when the navigation resolves, then the user is shown an appropriate 'not found' message rather than a blank or crashed screen
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to receive timely push notifications triggered by meaningful personal milestones, such as completing a significant number of activities, approaching an honorarium threshold, or having my annual impact summary ready to view
So that So that I feel recognized for my volunteer work and am prompted to engage with features that show the value of my contributions, increasing my motivation to continue
- Given a peer mentor logs their 25th (or 50th, 100th) activity, when the activity is saved, then a milestone push notification is sent congratulating them and linking to their personal statistics screen
- Given a Blindeforbundet peer mentor is about to receive their 3rd assignment (the honorarium-triggering threshold), when the 3rd assignment dispatch is created, then a notification informs them of their upcoming honorarium eligibility
- Given a peer mentor's annual impact summary has been calculated and is available, when the calculation job completes, then a push notification invites them to view their year-end impact summary
- +2 more
As a As a Coordinator
I want I want to automatically receive a push notification when any peer mentor in my organizational scope sets themselves on a pause (temporarily deactivates) or lifts a pause to become available again
So that So that I can adjust assignment dispatch decisions in real time, avoid sending new assignments to unavailable mentors, and re-engage returning mentors promptly
- Given a peer mentor sets their status to 'paused', when the pause is saved to the database, then the responsible coordinator receives a push notification within 60 seconds identifying the peer mentor and the pause action
- Given a peer mentor resumes availability by lifting a pause, when the status update is saved, then the responsible coordinator receives a notification confirming the mentor's return to active status
- Given a peer mentor provides a pause reason (e.g., 'holiday until March 15'), when the coordinator notification is sent, then the reason is included in the notification body
- +2 more
As a As a user
I want I want to mark individual notifications as read by tapping them, mark all notifications as read with a single action, and delete individual notifications by swiping them away
So that So that I can maintain a clean, actionable notification list that accurately reflects which items still require my attention
- Given a user taps an unread notification item, when the tap is processed, then the notification is marked as read in the database and the unread indicator is removed from that item
- Given a user swipes a notification item to the left, when the swipe reaches the delete threshold, then a delete confirmation action is revealed; when confirmed, the notification is deleted from the database and removed from the list
- Given a user taps 'Mark all as read', when the action is confirmed, then all notifications in the list are updated to read status in a single batch operation and all unread indicators are removed
- +2 more
As a As a user
I want I want tapping a push notification to open the app and navigate me directly to the specific screen relevant to that notification, without requiring me to manually navigate from the home screen
So that So that I can act on notifications immediately with the minimum number of steps, especially on mobile where navigating through multiple screens is slow and error-prone
- Given a user taps a 'new assignment' push notification while the app is terminated, when the app launches, then after successful authentication verification the user is navigated to the Assignment Detail screen for that specific assignment
- Given a user taps a push notification while the app is backgrounded, when the app comes to foreground, then the user is navigated to the target screen without passing through the home screen
- Given the target entity no longer exists when the notification is tapped (e.g., assignment was withdrawn), when the navigation resolves, then the user is shown an appropriate 'not found' message rather than a blank or crashed screen
- +2 more
As a As a user
I want I want to mark individual notifications as read by tapping them, mark all notifications as read with a single action, and delete individual notifications by swiping them away
So that So that I can maintain a clean, actionable notification list that accurately reflects which items still require my attention
- Given a user taps an unread notification item, when the tap is processed, then the notification is marked as read in the database and the unread indicator is removed from that item
- Given a user swipes a notification item to the left, when the swipe reaches the delete threshold, then a delete confirmation action is revealed; when confirmed, the notification is deleted from the database and removed from the list
- Given a user taps 'Mark all as read', when the action is confirmed, then all notifications in the list are updated to read status in a single batch operation and all unread indicators are removed
- +2 more
As a As a user
I want I want tapping a push notification to open the app and navigate me directly to the specific screen relevant to that notification, without requiring me to manually navigate from the home screen
So that So that I can act on notifications immediately with the minimum number of steps, especially on mobile where navigating through multiple screens is slow and error-prone
- Given a user taps a 'new assignment' push notification while the app is terminated, when the app launches, then after successful authentication verification the user is navigated to the Assignment Detail screen for that specific assignment
- Given a user taps a push notification while the app is backgrounded, when the app comes to foreground, then the user is navigated to the target screen without passing through the home screen
- Given the target entity no longer exists when the notification is tapped (e.g., assignment was withdrawn), when the navigation resolves, then the user is shown an appropriate 'not found' message rather than a blank or crashed screen
- +2 more
As a As a Organization Administrator
I want I want to configure the notification scenario rules for my organization, including thresholds for inactivity reminders, follow-up windows, and which scenario categories are active for my peer mentors and coordinators
So that So that the notification system reflects my organization's specific operational processes and compliance requirements without requiring an app update each time a policy changes
- Given an organization administrator navigates to Admin Settings, when they access the Notification Scenarios section, then they see all configurable scenario parameters with their current values and defaults clearly displayed
- Given an administrator changes the inactivity reminder threshold from 14 to 7 days, when the change is saved, then the next Edge Function evaluation uses 7 days as the threshold for all peer mentors in that organization
- Given an administrator disables a scenario category globally (e.g., disables 'Inactivity Reminders' for all users), when a qualifying event occurs, then no users in that organization receive that notification type regardless of their individual preferences
- +2 more
As a As a user
I want I want to open a dedicated notification center that lists all my received push notifications grouped by date, with clear visual distinction between read and unread items
So that So that I can review all recent system alerts, assignment updates, reminders, and activity milestones in one place without missing anything important
- Given an authenticated user has received at least one notification, when they navigate to the Notifications tab, then the notifications screen loads with all notifications grouped by date (Today, Yesterday, Earlier)
- Given a user has unread notifications, when the screen loads, then unread items are visually distinct from read items with bold text and an unread indicator dot
- Given notifications exist, when the screen loads, then each notification item displays category icon, title, body preview, and relative timestamp
- +2 more
As a As a user
I want I want to open a notification settings screen with a global master toggle and individual toggles for each notification category, and have my preferences saved persistently
So that So that I only receive the types of notifications that are relevant to my role and working style, reducing notification fatigue without missing critical alerts
- Given a user navigates to Notification Settings, when the screen loads, then all current preference states are fetched from push_notification_configs and rendered accurately
- Given a user toggles off the global master switch, when the change is saved, then no push notifications of any category are sent to that user until the master switch is re-enabled
- Given a user disables a specific category (e.g., follow-up reminders), when a qualifying scenario event fires for that user, then no notification is dispatched for that category
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to receive a friendly push notification reminder when I have not logged any activities for an extended period that exceeds my organization's configured inactivity threshold
So that So that I am prompted to log activities I may have forgotten to register, keeping my statistics accurate and ensuring the organization's Bufdir reporting data is complete
- Given a peer mentor has not logged any activity for longer than the inactivity threshold, when the scheduled Edge Function runs, then a push notification is enqueued for that peer mentor
- Given a peer mentor is on an availability pause, when the inactivity check runs, then no inactivity reminder is sent to avoid unnecessary notifications
- Given a peer mentor logs an activity after receiving an inactivity reminder, when the next scheduled run occurs, then no reminder is sent since the inactivity condition is no longer met
- +2 more
As a As a user
I want I want the option to sync activities and scheduled events I have registered to my device's native calendar application, so that activity and event entries appear alongside my personal appointments
So that So that I reduce the risk of missing or double-booking scheduled peer support sessions by seeing them in the same calendar I use for daily planning
- Given a user has not previously granted calendar permissions, when they first trigger a calendar sync action, then the OS permission dialog is shown with a clear rationale message
- Given calendar permission is granted, when a user creates an activity or event and chooses to add it to their calendar, then a calendar entry is created in the device's default calendar with correct title, date, time, and duration
- Given a user edits a previously synced activity (e.g., changes the date), when the edit is saved, then the corresponding calendar entry is updated to reflect the new details
- +2 more
As a As a user
I want I want to open a dedicated notification center that lists all my received push notifications grouped by date, with clear visual distinction between read and unread items
So that So that I can review all recent system alerts, assignment updates, reminders, and activity milestones in one place without missing anything important
- Given an authenticated user has received at least one notification, when they navigate to the Notifications tab, then the notifications screen loads with all notifications grouped by date (Today, Yesterday, Earlier)
- Given a user has unread notifications, when the screen loads, then unread items are visually distinct from read items with bold text and an unread indicator dot
- Given notifications exist, when the screen loads, then each notification item displays category icon, title, body preview, and relative timestamp
- +2 more
As a As a user
I want I want to open a notification settings screen with a global master toggle and individual toggles for each notification category, and have my preferences saved persistently
So that So that I only receive the types of notifications that are relevant to my role and working style, reducing notification fatigue without missing critical alerts
- Given a user navigates to Notification Settings, when the screen loads, then all current preference states are fetched from push_notification_configs and rendered accurately
- Given a user toggles off the global master switch, when the change is saved, then no push notifications of any category are sent to that user until the master switch is re-enabled
- Given a user disables a specific category (e.g., follow-up reminders), when a qualifying scenario event fires for that user, then no notification is dispatched for that category
- +2 more
As a As a Coordinator
I want I want to receive a push notification when one or more peer mentors in my organization have an assignment that has remained unacknowledged beyond the configured threshold (default 10 days)
So that So that I can proactively follow up with the peer mentor through alternative channels (phone, in-person) before the situation becomes a serious lapse in care delivery
- Given a peer mentor's assignment crosses the 10-day unacknowledged threshold, when the Edge Function runs, then the responsible coordinator receives a push notification naming the peer mentor and assignment
- Given multiple peer mentors in the coordinator's scope have overdue assignments on the same day, when the Edge Function runs, then a single digest notification is sent listing all overdue cases rather than one notification per case
- Given a coordinator taps the overdue assignment notification, when the app opens, then they are navigated to the Assignment Status Screen scoped to show overdue assignments
- +2 more
As a As a user
I want I want the option to sync activities and scheduled events I have registered to my device's native calendar application, so that activity and event entries appear alongside my personal appointments
So that So that I reduce the risk of missing or double-booking scheduled peer support sessions by seeing them in the same calendar I use for daily planning
- Given a user has not previously granted calendar permissions, when they first trigger a calendar sync action, then the OS permission dialog is shown with a clear rationale message
- Given calendar permission is granted, when a user creates an activity or event and chooses to add it to their calendar, then a calendar entry is created in the device's default calendar with correct title, date, time, and duration
- Given a user edits a previously synced activity (e.g., changes the date), when the edit is saved, then the corresponding calendar entry is updated to reflect the new details
- +2 more
As a As a user
I want I want to open a dedicated notification center that lists all my received push notifications grouped by date, with clear visual distinction between read and unread items
So that So that I can review all recent system alerts, assignment updates, reminders, and activity milestones in one place without missing anything important
- Given an authenticated user has received at least one notification, when they navigate to the Notifications tab, then the notifications screen loads with all notifications grouped by date (Today, Yesterday, Earlier)
- Given a user has unread notifications, when the screen loads, then unread items are visually distinct from read items with bold text and an unread indicator dot
- Given notifications exist, when the screen loads, then each notification item displays category icon, title, body preview, and relative timestamp
- +2 more
As a As a user
I want I want to open a notification settings screen with a global master toggle and individual toggles for each notification category, and have my preferences saved persistently
So that So that I only receive the types of notifications that are relevant to my role and working style, reducing notification fatigue without missing critical alerts
- Given a user navigates to Notification Settings, when the screen loads, then all current preference states are fetched from push_notification_configs and rendered accurately
- Given a user toggles off the global master switch, when the change is saved, then no push notifications of any category are sent to that user until the master switch is re-enabled
- Given a user disables a specific category (e.g., follow-up reminders), when a qualifying scenario event fires for that user, then no notification is dispatched for that category
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to receive an immediate push notification on my device when a coordinator dispatches a new assignment to me, regardless of whether the app is open, backgrounded, or closed
So that So that I can respond promptly to new assignments without relying on coordinators to contact me through separate channels such as phone or email
- Given a coordinator dispatches an assignment to a peer mentor, when the database record is inserted, then the Edge Function triggers within 30 seconds and enqueues a push notification via FCM/APNs
- Given the peer mentor's app is in the foreground when the notification arrives, when the FCM message is received, then a local notification banner is displayed at the top of the screen
- Given the peer mentor's app is backgrounded or terminated, when the FCM message is received, then a system tray notification is displayed
- +2 more
As a As a Peer Mentor (Likeperson)
I want I want to automatically receive a push notification reminder 10 days after an assignment was dispatched to me if I have not yet opened or acknowledged it
So that So that I am prompted to follow up on assignments that may have been overlooked, ensuring no individual needing peer support is left without a response due to a missed notification
- Given a peer mentor received an assignment dispatch 10 days ago and has not created a read receipt, when the daily Edge Function runs, then a follow-up push notification is enqueued for that peer mentor
- Given a peer mentor received an assignment dispatch 10 days ago but has already opened and acknowledged it, when the daily check runs, then no follow-up notification is sent
- Given a follow-up notification is sent, when the peer mentor taps it, then they are deep-linked to the specific assignment requiring acknowledgement
- +2 more