Submit a Mileage Reimbursement Claim for a Peer Support Visit
Peer mentors frequently travel to meet contacts and need a quick, frictionless way to log mileage claims. The form should pre-fill today's date, allow entry of from/to route or direct distance in kilometers, and instantly display the calculated reimbursement amount based on the organization's current rate. The workflow must minimize cognitive load — defaulting to the most common scenario (single-leg trip, no receipt required under 50 km) — while still supporting more complex cases. Auto-approval must trigger silently when the claim is below the configured threshold.
User Story
Audience Summaries
Mileage reimbursement is the most frequent financial interaction peer mentors have with the platform, and friction in this flow is directly correlated with volunteer disengagement. This story delivers a fast, pre-filled claim form with real-time reimbursement calculation and silent auto-approval for low-value claims — removing the single largest pain point in the volunteer compensation cycle. HLF and Blindeforbundet have explicitly prioritized this capability in Phase 2, recognizing that uncompensated or delayed travel reimbursement is a leading driver of volunteer attrition. Automating routine approvals also reduces coordinator workload, freeing staff capacity for higher-complexity attestation decisions and improving overall program efficiency.
Rated critical priority, this story has broad cross-functional scope: it touches the mileage claim form UI, distance prefill service integration, real-time calculation engine, auto-approval threshold configuration, coordinator attestation queue, claim status display, and offline sync via Supabase. The seven acceptance criteria span online and offline scenarios, requiring thorough integration testing across network conditions. No upstream story dependencies are listed, making this an eligible early-sprint candidate, but the distance prefill service and Supabase mileage adapter must be available or mocked before end-to-end testing is possible. UAT should include peer mentor volunteers testing the form under realistic mobile and connectivity conditions.
Delivery risk centers on offline sync reliability and threshold configuration accuracy.
The mileage claim form requires: date pre-fill on load with distance field auto-focus; dual route input (from/to address) triggering the distance prefill service with an estimated km result displayed to the user; a real-time reimbursement calculator bound to the distance field and the organization's configured rate-per-km (fetched from config, not hardcoded); conditional auto-approval logic comparing claim total against a configurable threshold before routing to the attestation queue or approving silently; persistence to the mileage claim repository with a status badge reflecting the resulting state. Offline support requires Supabase offline adapter integration with queue-and-sync behavior on reconnect. Edge cases include prefill service failures (fallback to manual entry), distance field validation, and threshold boundary conditions.
Acceptance Criteria
- Given I open the mileage entry form, When the form loads, Then today's date is pre-filled and the distance field is focused
- Given I enter a from-address and a to-address in the route input fields, When both fields are populated, Then the system attempts to prefill the distance using the distance prefill service and displays an estimated km value
- Given I have entered or confirmed a distance in kilometers, When I view the reimbursement display, Then the calculated reimbursement amount updates in real time based on the organization's configured rate per km
- Given my claim is below the organization's auto-approval threshold (e.g., under 50 km with no additional expenses), When I submit the claim, Then the claim is automatically approved without requiring coordinator review and I receive a confirmation
- Given my claim exceeds the auto-approval threshold, When I submit the claim, Then the claim is placed in the coordinator's attestation queue and I am informed that it is pending review
- Given I submit the form, When the submission succeeds, Then the claim is persisted to the mileage claim repository and the claim status badge reflects the correct state (auto-approved or pending)
- Given I am offline when submitting, When connectivity is restored, Then the claim is synced via the Supabase mileage adapter without data loss
Business Value
Mileage reimbursement is a primary financial touchpoint for peer mentors — uncompensated travel is a leading reason volunteers disengage. Automating calculation and approval for common low-value claims removes the single largest friction point in the reimbursement cycle, reduces coordinator workload, and directly supports volunteer retention across all participating organizations (HLF and Blindeforbundet explicitly prioritize this in Phase 2).
Components
- Mileage Entry Form ui
- Real-Time Reimbursement Display Widget ui
- Route Input Fields Widget ui
- Distance Input Field Widget ui
- Mileage Claim Service service
- Auto-Approval Threshold Evaluator service
- Mileage Reimbursement Calculation Service service
- Distance Prefill Service service
- Mileage Claim Repository data
- Organisation Rate Configuration Repository data
- Supabase Mileage Adapter infrastructure
- Local Distance Cache infrastructure
- Expense Registration Screen ui
- Expense Form BLoC service
- Expense Validation Service service
- Expense Submission Service service