Define orchestrator service interface and types
epic-pause-status-notifications-backend-pipeline-task-005 — Define the TypeScript interface for the Pause Notification Orchestrator service including input types (mentor ID, transition event, timestamp), output types (dispatch result, error details), and the coordinator resolution contract. Establish the service boundary before implementation begins.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Defining the interface before implementation is intentional — it establishes the contract that both the webhook handler (consumer) and the orchestrator (provider) must honor. This enables parallel development: the webhook handler can call orchestrate() against a stub implementation while the real orchestrator is built. Keep the CoordinatorResolutionContract as a separate interface (not inlined into the orchestrator) so it can be independently mocked in tests. The notificationPreferences field on Coordinator should reference the actual notification channel used (push notification token, email) — align with however the peer mentor pause feature sends coordinator alerts per the product spec (push notifications are mentioned in the HLF requirements).
Testing Requirements
No runtime tests for type definitions. However, write a compile-time test file (types.test-d.ts using tsd or expectType assertions) that verifies: (1) a valid PauseNotificationInput satisfies the interface, (2) a mock orchestrator implementing IPauseNotificationOrchestrator compiles without errors, (3) PauseNotificationResult discriminated union narrows correctly in if (result.ok) branches.
These compile-time tests prevent interface regressions during refactoring.
Supabase Edge Functions have cold start latency that may push coordinator notification delivery beyond the 5-second SLA, particularly during low-traffic periods when the function is not warm.
Mitigation & Contingency
Mitigation: Keep the Edge Function lightweight — delegate all heavy logic to the orchestrator layer and avoid large dependency bundles. Measure p95 end-to-end latency in staging and document actual SLA achievable.
Contingency: If cold start latency consistently breaches 5 seconds, introduce a keep-warm ping from the nightly-scheduler or document the actual p95 latency in the feature spec and adjust the acceptance criterion to reflect the realistic bound.
Supabase database webhooks may fire duplicate events for a single status change under retry conditions, causing coordinators to receive multiple identical notifications for one pause event.
Mitigation & Contingency
Mitigation: Add idempotency checking in the webhook handler using the event timestamp and peer mentor ID. Store a notification dispatch record in the pause-status-record-repository and skip dispatch if a record for the same event already exists.
Contingency: If duplicates slip through in production, add a de-duplication filter in the notification centre UI layer so the coordinator sees at most one card per event, and implement a cleanup job for the notifications table.
A peer mentor with multi-chapter membership may have more than one responsible coordinator. The orchestrator design currently targets a single coordinator, and resolving multiple recipients may require schema changes to the org membership query.
Mitigation & Contingency
Mitigation: Review the multi-chapter-membership-service patterns before implementing the orchestrator's coordinator resolution. Design the dispatcher call to accept an array of coordinator IDs from the outset so adding multiple recipients is non-breaking.
Contingency: If multi-coordinator dispatch is out of scope for this epic, document the limitation and create a follow-up task. Default to the primary coordinator (lowest chapter hierarchy level) as the single recipient in the interim.