FCM Notification Dispatcher
Component Detail
Description
Shared Firebase Cloud Messaging dispatch function that sends push notifications to device tokens and writes in-app notification records to the database. Reused across all notification features including assignment reminders and certificate expiry alerts. Handles delivery failures with retry logic.
fcm-notification-dispatcher
Summaries
The FCM Notification Dispatcher is the shared delivery engine that powers every push and in-app notification across the platform — from mentor assignment reminders to certificate expiry alerts and pause status changes. By centralizing notification delivery into a single reusable component with built-in retry logic, the organization significantly reduces the risk of silent delivery failures that would leave users uninformed of critical program events. This reliability directly protects the user experience quality that drives mentor and coordinator engagement. The shared architecture also means that every new notification feature added to the platform inherits production-grade delivery reliability at zero additional engineering cost, accelerating the roadmap for future communication features.
As a shared component consumed by all notification features, the FCM Notification Dispatcher carries the highest delivery risk of any component in the notification system — a bug or regression here affects every feature simultaneously. This warrants a thorough testing investment: unit tests for each dispatch path (push-only, in-app-only, multi-channel), retry logic under simulated FCM failures, and device token resolution edge cases (empty token list, expired tokens). Medium complexity reflects the retry logic and multi-channel coordination. The component should be delivered and stabilized before any feature-specific notification work begins.
Deployment requires Firebase project configuration and Supabase notification table provisioning. Monitoring and alerting on FCM delivery failure rates should be part of the acceptance criteria, as silent failures are operationally invisible without instrumentation.
This dispatcher wraps the Firebase Admin SDK's messaging API and exposes three dispatch methods: `dispatchPush` (FCM only), `dispatchInApp` (Supabase write only), and `dispatchMultiChannel` (both). `getDeviceTokens` queries the device registration table and should handle users with no registered tokens gracefully by returning an empty list and short-circuiting dispatch. FCM delivery failures fall into two categories: permanent (invalid token — remove from registration table) and transient (server error — retry with exponential backoff up to a configured maximum). The `handleDeliveryFailure` function must distinguish these cases.
`retryDispatch` should look up the original notification record by ID and re-attempt delivery, useful for manual recovery flows. Because this component writes to the `notifications` table, its Supabase client instance should be the same privileged service-role client used elsewhere to avoid RLS policy conflicts. Shared consumers must pass a fully constructed `NotificationPayload` — this dispatcher is intentionally payload-agnostic.
Responsibilities
- Dispatch FCM push notifications to one or more device tokens
- Write in-app notification records to the notifications table in Supabase
- Handle FCM delivery errors and retry transient failures
- Support multi-channel dispatch (push and in-app) in a single call
Interfaces
dispatchPush(recipientId: String, payload: NotificationPayload): DispatchResult
dispatchInApp(recipientId: String, payload: NotificationPayload): DispatchResult
dispatchMultiChannel(recipientId: String, payload: NotificationPayload): DispatchResult
getDeviceTokens(userId: String): List<String>
handleDeliveryFailure(error: FCMError): void
retryDispatch(notificationId: String): DispatchResult
Relationships
Related Data Entities (2)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on