Track Expense Claim Approval Status in Real Time
After submitting an expense claim, peer mentors need visibility into its progress through the approval workflow. The app should display a claim status badge (submitted, pending review, approved, rejected) on each claim, show a timeline of status events, and push a notification when the status changes. Claims that were auto-approved should immediately show an approved status. Real-time updates via Supabase subscriptions should reflect coordinator actions without requiring the user to manually refresh.
User Story
Audience Summaries
This high-priority story directly addresses volunteer retention — a critical business risk for peer mentor programs. Peer mentors who cannot see the status of submitted expense claims are statistically more likely to abandon reimbursement altogether, reducing volunteer engagement and increasing coordinator overhead from status inquiry messages. Real-time approval visibility eliminates this friction point, reinforcing trust in the platform and demonstrating that the organization values its volunteers' time and contributions. For programs running at scale, reducing reimbursement abandonment directly improves delivery effectiveness.
Push notifications and instant status transitions for auto-approved claims create a modern, responsive experience that supports long-term volunteer satisfaction, retention, and ultimately the quality of peer support services delivered in the field.
This story has a hard dependency on story-travel-expense-registration-peer-mentor-001 and must be sequenced after the expense submission flow is stable. The core delivery complexity lies in configuring Supabase real-time subscriptions correctly — ensuring subscriptions are scoped per authenticated user and cleaned up on navigation to prevent memory leaks. Push notification integration requires coordination across iOS (APNs) and Android (FCM) delivery channels. UAT must cover the full coordinator workflow: submission → pending review → approval or rejection, plus the auto-approval bypass path.
Rejection reason display is a separate UI requirement needing UX sign-off on message formatting. Estimated effort is 5–8 days including edge case testing around subscription reconnection on poor networks and offline notification queuing. Stakeholders include coordinators (notification accuracy) and volunteer program managers (trust metrics).
Implementation requires setting up a Supabase real-time subscription on the expense_claims table, filtered by the authenticated user's ID, listening for UPDATE events on the status field. The status state machine should model: submitted → pending_review → approved or rejected, with a separate auto-approved flag that bypasses the pending_review state entirely. UI components needed: a StatusBadge widget with distinct colors per state, and a StatusTimeline widget rendering chronological events fetched from an expense_claim_events or audit log table. Push notifications require a server-side Supabase Edge Function or database trigger dispatching to Firebase Cloud Messaging when coordinator actions are recorded.
Subscription lifecycle must be managed carefully — subscribe on widget mount, unsubscribe on dispose to prevent duplicate event handling. Rejection reason should be stored as a nullable text field on the claim record and displayed conditionally in the detail view. Test reconnection behavior after app backgrounding.
Acceptance Criteria
- Given I have submitted an expense claim, when I view my expense history, then each claim shows a status badge indicating its current state
- Given I open a specific claim, when the detail view loads, then a status timeline is displayed showing each status change with timestamps
- Given a coordinator approves or rejects my claim, when the action is processed, then my app updates the claim status in real time without requiring a manual refresh
- Given my claim is auto-approved, when the submission completes, then the status immediately shows 'Approved' and no coordinator action is pending
- Given my claim is rejected, when I view the detail, then the rejection reason provided by the coordinator is displayed
- Given a status change occurs, when I have notifications enabled, then I receive a push notification informing me of the update
Business Value
Transparency in the approval process reduces the number of status inquiry messages coordinators receive and gives peer mentors confidence that their claims are being processed. Real-time status updates reinforce trust in the system and reduce the perception that submitted claims are lost, which is a common reason volunteers stop claiming reimbursement.
Components
- Expense Summary Card ui
- Claim Status Audit Timeline ui
- Claim Status Badge ui
- Claim Events Repository data
- Expense Claim Status Repository data
- Supabase Realtime Approval Subscription infrastructure
- Approval Status Notification Service service
- Expense Repository data