Notification Trigger Service
Component Detail
Description
Supabase Edge Function that listens to database change events and dispatches role-aware FCM push notifications. Triggers include new peer mentor assignments, activity status changes, and approaching deadline warnings. Respects per-user per-category opt-in preferences before dispatching.
notification-trigger-service
Summaries
The Notification Trigger Service is the server-side engine that converts key business events — such as peer mentor assignments, activity status transitions, and approaching deadlines — into timely push notifications reaching the right users. By respecting individual per-category opt-in preferences before dispatching, the platform avoids notification fatigue and demonstrates respect for user autonomy, which is critical for sustained engagement in education and mentoring contexts. This backend service enables proactive user communication without requiring any manual intervention, reducing coordination overhead for program coordinators and ensuring participants stay informed and on track, directly improving program completion rates and measurable outcomes.
This is a high-complexity backend component deployed as a Supabase Edge Function, introducing dependencies on Supabase database webhook configuration, the FCM Admin SDK, and the Notification Preferences Repository. Database webhook setup must be coordinated with the infrastructure team early, as webhook misconfiguration is a common integration failure point. The component must be tested against all three trigger event types independently: assignment events, status change events, and deadline approaching events. Preference evaluation logic requires thorough test coverage to prevent unwanted notification dispatch.
Deployment to Supabase Edge Functions requires Deno-compatible TypeScript and has its own CI/CD pipeline separate from the Flutter app — factor this into release coordination planning.
Deployed as a Supabase Edge Function in a Deno runtime, this service subscribes to Supabase database webhooks via pg_net or Supabase's built-in webhook triggers. Each handler (`handleAssignmentEvent`, `handleStatusChangeEvent`, `handleDeadlineApproachingEvent`) receives a structured database change event, extracts relevant entity IDs, and calls `buildPayload(type, data)` to construct an FCM-compatible notification payload. Before dispatch, `dispatchToUser()` queries the Notification Preferences Repository to check per-user per-category opt-in status — skip dispatch if opted out. `dispatchToRole()` retrieves FCM tokens for all users matching a role within an organization via the FCM Token Manager.
Payload delivery uses the Firebase Admin SDK's `messaging().send()` or `messaging().sendMulticast()`. Ensure idempotency by checking for duplicate event processing, and implement structured error logging for failed dispatches to support observability.
Responsibilities
- Subscribe to Supabase database webhooks for triggering events
- Evaluate per-user notification preferences before dispatch
- Construct role-aware notification payload and send via FCM Admin SDK
Interfaces
handleAssignmentEvent(event)
handleStatusChangeEvent(event)
handleDeadlineApproachingEvent(event)
dispatchToUser(userId, payload)
dispatchToRole(role, organizationId, payload)
buildPayload(type, data)
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (3)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on