Reminder Scheduler Service
Component Detail
Description
Backend service that orchestrates the scheduling and lifecycle of follow-up reminder jobs. Uses Supabase pg_cron or Edge Function cron triggers to evaluate open assignments daily, determining which require reminders or escalations based on last_contact_date and org-specific thresholds.
reminder-scheduler-service
Summaries
The Reminder Scheduler Service is the engine that keeps the peer mentoring programme actively monitored without requiring any manual intervention from programme staff. By running a daily automated check across all open assignments, it ensures that every student receives timely follow-up and that coordinators are alerted before small lapses become serious welfare concerns. This automation directly reduces the administrative burden on coordinators, allowing them to focus on meaningful interventions rather than manually tracking response patterns. It also provides institutional stakeholders with confidence that the platform enforces programme standards consistently and at scale, supporting compliance and safeguarding obligations.
This is a high-complexity backend service and one of the most critical components in the reminder pipeline. It has four direct dependencies — `reminder-evaluation-service`, `reminder-dispatch-service`, `assignment-contact-tracking-repository`, and `reminder-config-repository` — all of which must be available and stable before end-to-end testing can begin. The cron infrastructure (Supabase pg_cron or Edge Function triggers) introduces deployment-specific configuration that must be validated in the staging environment. Key risks include cron misconfiguration, duplicate dispatch due to race conditions or retry logic, and silent failures if the job errors without alerting.
Mitigation: implement robust logging via `logReminderRun(result)`, set up alerting on job failures, and ensure idempotency through the `hasReminderAlreadySent` guard. This component should be on the critical path for the reminder feature release.
The service is triggered by a Supabase pg_cron schedule or an Edge Function cron endpoint calling `runDailyReminderCheck()`. This method fetches all open assignments via `getAssignmentsDueForReminder()` and `getAssignmentsDueForEscalation()`, then iterates each through `evaluateAssignment(assignmentId)`. Before dispatching, `hasReminderAlreadySent(assignmentId, windowStart)` acts as an idempotency guard to prevent duplicate notifications within the same evaluation window. Qualifying assignments are handed off to `reminder-dispatch-service` for actual notification delivery.
`scheduleNextCheck()` may be used to programmatically confirm or reschedule the next run depending on the cron strategy. All run results, including counts of evaluated, reminded, escalated, and skipped assignments, should be persisted via `logReminderRun(result)` for observability. Ensure the service handles database errors per-assignment with per-record try/catch so a single bad record does not abort the entire daily run.
Responsibilities
- Run daily cron job to evaluate all open assignments
- Determine which assignments are past the reminder threshold
- Determine which escalations are past the secondary threshold
- Trigger reminder and escalation dispatch for qualifying assignments
- Prevent duplicate reminder dispatch within the same window
Interfaces
runDailyReminderCheck()
evaluateAssignment(assignmentId)
getAssignmentsDueForReminder()
getAssignmentsDueForEscalation()
hasReminderAlreadySent(assignmentId, windowStart)
scheduleNextCheck()
logReminderRun(result)
Relationships
Dependencies (4)
Components this component depends on
Dependents (1)
Components that depend on this component