Integrate FCM dispatcher for push notifications
epic-pause-status-notifications-backend-pipeline-task-008 — Wire the FCM notification dispatcher into the orchestrator to send push notifications for both pause and resume events. Retrieve FCM tokens for coordinator and mentor from the notification token store, invoke the dispatcher for each recipient, handle delivery failures gracefully without blocking in-app channel dispatch, and log FCM response codes.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use FCM HTTP v1 API (not legacy FCM API which is deprecated). Authentication requires a short-lived OAuth2 access token derived from the service account JSON — implement `getAccessToken(serviceAccountJson)` using the google-auth-library pattern adapted for Deno fetch. Token cache the access token for the duration of the function invocation (it's valid for 1 hour). Structure as `dispatchFcmNotifications(tokens: string[], payload: FcmPayload): Promise
Use `Promise.allSettled` not `Promise.all` so one token failure doesn't abort others. For stale token cleanup, batch the DELETE query rather than one per token. Coordinate with mobile team to confirm the FCM data payload keys match the Flutter notification router's expected schema.
Testing Requirements
Unit tests: mock FCM HTTP client and verify (a) parallel dispatch invoked for both recipients, (b) missing token skips dispatch without error, (c) FCM UNREGISTERED response triggers token deletion, (d) FCM HTTP 500 is caught and logged without throwing. Integration tests: use a FCM test project or mock server to verify correct HTTP request shape (Authorization header, payload structure). Verify Promise.allSettled semantics — one rejection must not prevent the other from completing. Performance test: assert both dispatches complete within 2000ms under mocked latency of 800ms per call.
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.