Scenario Prompt Scheduler Service
Component Detail
Description
Orchestrates the scheduled evaluation and dispatch of scenario-based prompts. Invoked by a recurring Supabase Edge Function cron job, it fetches recent activities, runs them through the rule engine, deduplicates already-sent prompts, and forwards new prompts to the push notification dispatcher.
scenario-prompt-scheduler
Summaries
The Scenario Prompt Scheduler is the operational backbone of the platform's proactive support capability — it ensures that time-sensitive peer mentor prompts are evaluated and delivered automatically, without any manual intervention from coordinators or programme staff. By running on a reliable cron schedule, deduplicating previously sent prompts, and coordinating with the push notification system, the scheduler guarantees that the right mentor receives the right prompt within the configured time window after a triggering activity. This automation reduces coordinator workload, eliminates human error in prompt timing, and allows the programme to scale to a much larger member base without proportional increases in staff effort.
The Scenario Prompt Scheduler is a high-complexity backend service with three direct dependencies: the scenario-rule-engine, prompt-history-repository, and push-notification-dispatcher. It is the final integration point for the entire scenario prompting pipeline and cannot be completed until all three dependencies are stable. The cron schedule cadence must be agreed with stakeholders early, as it affects prompt delivery latency guarantees. Key delivery risks include failure handling for partial batch runs, idempotency under repeated cron invocations if a previous run did not complete, and edge cases where the push dispatcher is unavailable.
Testing should include load scenarios with large activity backlogs and duplicate prompt prevention verification.
ScenarioPromptScheduler is invoked by a Supabase Edge Function cron trigger calling runScheduledEvaluation(). fetchEligibleActivities() queries activities created within the configured look-back window (e.g., last 24 hours) that have not yet been evaluated. For each activity, the rule engine's evaluateRules() is called, collecting TriggeredScenario results into a candidate list. deduplicatePrompts() cross-references candidates against prompt-history-repository to filter already-dispatched prompt IDs, preventing re-delivery.
dispatchPrompts() forwards the deduplicated list to push-notification-dispatcher in batches. recordSentPrompts() writes the dispatched prompt IDs back to prompt-history-repository atomically to ensure idempotency. The scheduler should implement structured logging for each phase to support operational debugging of missed or duplicate prompts.
Responsibilities
- Retrieve activities eligible for scenario evaluation within the look-back window
- Invoke the rule engine for each eligible activity
- Deduplicate prompts against sent prompt history
- Forward new prompts to the push notification dispatcher
- Record sent prompts to prevent re-delivery
Interfaces
runScheduledEvaluation(): Future<void>
fetchEligibleActivities(DateTime since): Future<List<Activity>>
deduplicatePrompts(List<TriggeredScenario> candidates): Future<List<TriggeredScenario>>
dispatchPrompts(List<TriggeredScenario> prompts): Future<void>
recordSentPrompts(List<String> promptIds): Future<void>
Relationships
Dependencies (3)
Components this component depends on
Dependents (1)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component