Reminder Dispatch Service
Component Detail
Description
Responsible for sending reminder and escalation notifications to the correct recipients. Composes the notification payload, delegates to the push notification delivery system for push delivery, and creates in-app notification records for display in the Notifications tab.
reminder-dispatch-service
Summaries
The Reminder Dispatch Service is the final delivery step that converts programme logic into real-world engagement. It ensures that when a peer mentor needs to be nudged — or a coordinator needs to be alerted — the right person receives the right message through the right channel at the right time. By handling both push notifications and in-app notification records, it provides a reliable, multi-surface communication layer that maximises message visibility and reduces the chance of critical alerts being missed. This capability strengthens the platform's value proposition as an active programme management tool rather than a passive record-keeping system, directly contributing to student outcomes and coordinator confidence.
A medium-complexity backend service with dependencies on `push-notification-service` and `in-app-notification-repository`, both of which must be stable before integration testing. The dual-channel delivery model (push + in-app) introduces two distinct failure modes that must be handled independently — a push delivery failure should not prevent the in-app record from being created, and vice versa. Testing requirements include: correct payload composition for both reminder and escalation types, successful delegation to the push service, in-app record persistence, and timestamp recording via `recordReminderSent` and `recordEscalationSent`. The timestamp recording is critical for the scheduler's idempotency logic, so any failure here should be treated as a blocking issue.
Plan for retry or dead-letter queue handling if push delivery fails.
The service separates payload construction from delivery, keeping `buildReminderPayload` and `buildEscalationPayload` as pure factory functions that can be unit tested without infrastructure dependencies. `dispatchReminder` targets the peer mentor and `dispatchEscalation` targets the coordinator — both delegate push delivery to `push-notification-service` and persist in-app records via `in-app-notification-repository` using `createInAppNotification(userId, payload)`. After successful dispatch, `recordReminderSent(assignmentId, sentAt)` and `recordEscalationSent(assignmentId, sentAt)` write the sent timestamp back to the assignment or reminder record, which the scheduler reads via `hasReminderAlreadySent`. Ensure these timestamp writes are atomic with the dispatch action or wrapped in a compensating transaction to prevent silent duplicate dispatches.
The `NotificationPayload` type should be a shared interface between this service and the push notification service to maintain a strict contract.
Responsibilities
- Compose reminder notification payload for peer mentor
- Compose escalation notification payload for coordinator
- Delegate push delivery to push notification service
- Persist in-app notification records to database
- Record reminder sent timestamp to prevent duplicates
Interfaces
dispatchReminder(assignment, peerMentor, orgSettings)
dispatchEscalation(assignment, coordinator, orgSettings)
buildReminderPayload(assignment): NotificationPayload
buildEscalationPayload(assignment, mentor): NotificationPayload
recordReminderSent(assignmentId, sentAt)
recordEscalationSent(assignmentId, sentAt)
createInAppNotification(userId, payload)
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (2)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on