Expose ScenarioRuleEngine and managers via Riverpod providers

epic-scenario-based-follow-up-prompts-core-logic-task-013 — Wire all three services into the Riverpod provider graph: scenarioRuleEngineProvider (depends on scenarioRuleRepositoryProvider and promptHistoryRepositoryProvider), scenarioConfigurationManagerProvider (depends on scenarioRuleRepositoryProvider), and scenarioDeepLinkHandlerProvider (depends on promptHistoryRepositoryProvider and go_router). Ensure providers are scoped correctly for multi-chapter support using family providers keyed by chapterId where appropriate.

high priority medium complexity backend pending backend specialist Tier 3

Acceptance Criteria

scenarioRuleEngineProvider is defined and resolves a ScenarioRuleEngine instance without runtime errors

scenarioConfigurationManagerProvider is defined and resolves a ScenarioConfigurationManager instance

scenarioDeepLinkHandlerProvider is defined and resolves a ScenarioDeepLinkHandler instance with go_router correctly injected

scenarioConfigurationManagerProvider.family(chapterId) creates an isolated manager instance per chapterId

Two calls to scenarioConfigurationManagerProvider.family('ch-1') and .family('ch-2') return distinct instances that do not share state

Providers use ref.watch() for dependencies — not ref.read() — to enable proper reactivity and disposal

All providers are defined in a single dedicated file (e.g., scenario_providers.dart) for discoverability

No circular dependencies exist in the provider graph

Provider definitions compile without errors via npm run build equivalent (flutter analyze / dart compile)

Technical Requirements

frameworks

Flutter

Riverpod

go_router

apis

go_router routerProvider (if using Riverpod + go_router integration)

data models

ScenarioRuleEngine

ScenarioConfigurationManager

ScenarioDeepLinkHandler

ScenarioRuleRepository

PromptHistoryRepository

performance requirements

Family providers must be automatically disposed when no longer watched (autoDispose) to prevent memory leaks from accumulating per-chapter instances

Provider initialization must be lazy (not eager) — instances created only on first access

security requirements

Providers must not expose internal repository instances directly — only expose the service layer

go_router reference in scenarioDeepLinkHandlerProvider must be obtained via Riverpod's routerProvider or equivalent, not via a global variable

Execution Context

Execution Tier

Tier 3

Tier 3 - 413 tasks

Can start after Tier 2 completes

View Full Execution Plan

Implementation Notes

Use Riverpod's Provider (not StateNotifierProvider or FutureProvider) for these service objects since ScenarioRuleEngine, ScenarioConfigurationManager, and ScenarioDeepLinkHandler are stateless service classes. Use .family modifier on scenarioConfigurationManagerProvider keyed by chapterId (String). Mark family providers as .autoDispose to avoid memory leaks when switching chapters. For go_router injection into scenarioDeepLinkHandlerProvider: if using the riverpod_go_router package, use routerProvider; otherwise pass a GoRouter reference through a dedicated goRouterProvider.

Define all three providers in lib/features/scenario/providers/scenario_providers.dart and export from a barrel file. Avoid putting provider definitions inside service class files — keep them in a dedicated providers layer.

Testing Requirements

Write provider graph tests using flutter_test with ProviderContainer. Test: (1) scenarioRuleEngineProvider resolves correctly with a ProviderContainer that overrides repository providers with fakes; (2) scenarioConfigurationManagerProvider.family('ch-A') and .family('ch-B') are distinct instances; (3) autoDispose behavior — after container.dispose(), no lingering references; (4) scenarioDeepLinkHandlerProvider resolves without requiring a real GoRouter (override with a fake RouterDelegate). Place provider tests in test/unit/scenario_providers_test.dart.

Component

Scenario Configuration Manager

service medium

Dependencies (3)

Implement ScenarioDeepLinkHandler that converts a triggered ScenarioContext (activityId, contactId, activityType, prefillDate, prefillDuration) into a go_router URI string targeting the activity registration wizard with pre-filled route arguments. Implement buildDeepLinkUri(context) and navigateToWizard(context, router). Support both cold-start (notification tap from terminated app) and warm-start (app in background) navigation paths. epic-scenario-based-follow-up-prompts-core-logic-task-007 Build the ScenarioConfigurationManager service that provides chapter-level rule management. Implement loadRulesForChapter(), saveRule(rule), deleteRule(ruleId), validateRuleJson(json), and seedDefaultTemplates(chapterId). Validation uses the JSON schema from task-001. Default templates are seeded when a chapter has no rules. Depends on ScenarioRuleRepository. epic-scenario-based-follow-up-prompts-core-logic-task-004 Implement the ScenarioRuleEngine.evaluate(activityMetadata, rules, promptHistory) method. The algorithm must check: contact type match, wellbeing flag conditions (any/all semantics), activity duration range, delay window eligibility (hours since activity end), and prompt cooldown guard via PromptHistoryRepository. Return EvaluationResult with matched rule or null with reason code. This is the highest-complexity component. epic-scenario-based-follow-up-prompts-core-logic-task-005

Epic Risks (2)

high impact medium prob scope

The Rule Engine must support a flexible JSON rule schema that can express compound conditions (e.g., contact_type AND wellbeing_flag AND delay_days). Underestimating schema expressiveness may require breaking changes to the rule format after coordinators have already configured rules.

Mitigation & Contingency

Mitigation: Define and freeze the rule JSON schema (trigger_type enum, metadata_conditions structure, delay logic) before any implementation begins; validate schema against all known HLF scenarios documented in the feature spec.

Contingency: If schema changes are needed after deployment, implement a schema version field and a migration utility that upgrades stored rules to the new format without coordinator intervention.

medium impact medium prob technical

Deep-link navigation to the activity wizard with pre-filled arguments may fail if the user's session has expired or if the wizard route is not yet mounted in the navigator stack, causing unhandled navigation exceptions.

Mitigation & Contingency

Mitigation: Implement session state check before navigation; if session is expired, redirect to biometric/login screen and store the pending deep-link URI for post-auth redirect using go_router's redirect mechanism.

Contingency: If post-auth redirect proves unreliable, fall back to navigating to the home screen with a visible action banner that re-triggers the wizard with pre-filled arguments.

Quick Links

All Tasks Execution Plan