Approval Status Notification Service
Component Detail
Description
Sends push notifications to the submitting peer mentor when their claim status changes (approved or rejected). Uses Supabase Realtime for real-time in-app delivery and FCM for background push when the app is not active. Includes the coordinator comment in rejection notifications.
approval-notification-service
Summaries
The Approval Status Notification Service directly improves peer mentor satisfaction and operational transparency by ensuring that every claim decision — whether approved or rejected — is communicated instantly to the submitter. When a coordinator rejects a claim, the rejection comment is included in the notification, eliminating the need for follow-up emails or manual communication and reducing administrative overhead. Real-time feedback shortens the feedback loop between submission and correction, accelerating reimbursement cycles and reducing coordinator workload from status enquiries. This responsiveness strengthens trust in the platform and supports retention of peer mentors who depend on timely expense reimbursement for their continued participation.
This component carries a medium complexity rating and spans two execution contexts — backend (Supabase Realtime + FCM integration) and mobile (in-app notification handling) — making it a cross-cutting concern that requires coordination between backend and mobile developers. Key delivery dependencies include FCM registration token storage being available per user, Supabase Realtime channel configuration for the claim_events table, and the notification payload localisation strings being finalised. Testing must cover both foreground (Supabase Realtime) and background (FCM) delivery paths, as well as failure scenarios where device tokens are stale or missing. Graceful error handling is required to ensure notification failures never block the underlying approval workflow transition, which must be validated explicitly during QA.
This shared service bridges Supabase Realtime and Firebase Cloud Messaging (FCM) to provide dual-path notification delivery. For in-app (foreground) delivery it subscribes to a Supabase Realtime channel scoped to a specific claimId and propagates status change events directly to the UI layer. For background delivery it resolves the claim submitter's FCM device token — likely stored in a user_devices or profiles table — and dispatches a structured push payload via the FCM HTTP v1 API. The `notifyStatusChange` interface is the primary entry point, orchestrating token resolution, payload construction via `buildNotificationPayload`, and delivery via `sendPushNotification`.
Subscription lifecycle methods (`subscribeToClaimEvents`, `unsubscribeFromClaimEvents`) must be called in tandem with screen navigation to prevent memory leaks. Error isolation is critical: FCM failures must be caught and logged without propagating to the caller.
Responsibilities
- Subscribe to claim status change events via Supabase Realtime
- Resolve device FCM token for the claim submitter
- Compose locale-appropriate notification payload with status and optional comment
- Deliver notification via FCM for background delivery
- Handle delivery failures gracefully without blocking workflow transitions
Interfaces
notifyStatusChange(claimId, newStatus, recipientUserId, comment)
subscribeToClaimEvents(claimId)
unsubscribeFromClaimEvents(claimId)
buildNotificationPayload(status, comment)
sendPushNotification(deviceToken, payload)
Relationships
Related Data Entities (3)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on