Scenario Rule Engine
Component Detail
Description
Core service that evaluates scenario rule definitions against recent activity metadata to determine whether a prompt should be generated. Supports JSON-configured rule sets with trigger types, delay windows, and metadata conditions such as contact type, reported wellbeing flags, and activity duration thresholds.
scenario-rule-engine
Summaries
The Scenario Rule Engine is the intelligence core of the automated peer-support prompting system. It analyses activity data in real time and determines precisely when and why a peer mentor should be prompted to act — transforming raw programme data into targeted, timely interventions. This capability is a key competitive differentiator: it enables the platform to deliver proactive, context-aware support at scale without requiring manual coordinator oversight of every interaction. By reducing missed support opportunities and improving the relevance of prompts, the engine directly contributes to better member outcomes, programme retention, and the organisation's ability to demonstrate measurable impact to funders.
The Scenario Rule Engine is the highest-complexity backend component in the scenario prompting feature and sits on the critical path for the entire prompt delivery pipeline. It depends on scenario-rule-repository for rule definitions and prompt-history-repository for deduplication context. Development should be prioritised early to allow downstream components (scenario-prompt-scheduler, notification dispatcher) to integrate against a stable interface. Unit testing must cover each trigger type, delay window boundary conditions, and combinations of metadata conditions.
Integration testing requires representative activity fixtures with varied contact types, wellbeing flags, and durations. Schema changes to ScenarioRule or Activity will require corresponding engine updates, so interface contracts should be locked before parallel development begins.
ScenarioRuleEngine is a backend service executing in a Supabase Edge Function or equivalent server environment. evaluateRules() is the primary entry point: it calls loadActiveRules() to fetch enabled ScenarioRule records for the chapter, then iterates rules calling matchesTrigger() and isWithinDelayWindow() for each. matchesTrigger() evaluates JSON-configured conditions including contact_type equality, wellbeing_flag set membership, and activity_duration threshold comparisons using a strategy pattern keyed on rule.triggerType. isWithinDelayWindow() compares DateTime.now() against activityDate plus rule.delayMinutes.
buildPromptPayload() assembles a ScenarioPrompt from matched rule fields and activity metadata for downstream dispatch. The engine is stateless per evaluation; all persistence is handled by its repository dependencies.
Responsibilities
- Load active scenario rules for a given organisation chapter
- Evaluate trigger conditions against activity metadata
- Apply delay logic to determine if the prompt window has opened
- Return matched scenarios with prompt payloads for dispatch
Interfaces
evaluateRules(String chapterId, Activity activity): Future<List<TriggeredScenario>>
loadActiveRules(String chapterId): Future<List<ScenarioRule>>
matchesTrigger(ScenarioRule rule, Activity activity): bool
isWithinDelayWindow(ScenarioRule rule, DateTime activityDate): bool
buildPromptPayload(ScenarioRule rule, Activity activity): ScenarioPrompt
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (2)
Data entities managed by this component