Submit Mileage Reimbursement Claim
Peer mentors frequently travel to meet contacts and must be able to claim mileage reimbursement quickly from the mobile app. The form should pre-fill the current date, show the applicable organizational rate, calculate the reimbursement amount in real time as the distance is entered, and support optional route fields (from/to locations). Claims under the configured distance threshold (e.g. 50 km with no additional expenses) should be submitted for automatic approval without requiring coordinator review.
User Story
Audience Summaries
Mileage reimbursement is the highest-frequency expense interaction for peer mentors, and friction in this process is directly linked to underreporting — a problem identified across all three partner organizations as the primary data quality challenge. This story eliminates the two main friction sources: manual calculation and coordinator bottlenecks for routine small claims. Auto-approval for sub-threshold distances means that the majority of reimbursements are processed instantly, giving volunteers immediate confirmation and reducing the administrative workload on coordinators by an estimated 60–80% for routine claims. Accurate mileage data also feeds directly into Bufdir activity reporting, improving compliance.
Faster, fairer reimbursement is a proven driver of volunteer retention, making this story a high-return investment in both data quality and workforce sustainability for partner organizations.
This is a high-priority story with well-defined acceptance criteria that make delivery scope clear. Effort spans form UI with real-time calculation, org-rate configuration integration, auto-approval routing logic, and draft state persistence. The auto-approval threshold logic requires close coordination with the admin portal team to ensure rate and threshold configurations are reliably available at claim submission time. QA must cover boundary conditions at the auto-approval threshold (exactly at threshold, one unit above/below), real-time calculation accuracy, draft restoration after app suspension, and correct rate display per organization.
No blocking dependencies are listed, making this an early-sprint candidate. Key delivery risk is rate synchronization lag — if the mobile client caches stale organizational rates, displayed previews may differ from server-calculated amounts, requiring a cache invalidation strategy. Rollout should include coordinator communication about the auto-approval behavior to align expectations.
The form requires a real-time calculation engine that multiplies entered distance against the org-specific rate fetched from the backend configuration API — this must trigger on every keystroke or distance field change without debounce delay to satisfy the acceptance criteria. The organizational rate must be loaded at screen open and cached locally for offline scenarios, with a staleness indicator if the rate cannot be refreshed. Auto-approval routing logic should live server-side: the client submits the claim and the backend applies the threshold check, returning either an approved confirmation or a pending-review status. This prevents threshold bypass via client manipulation.
Draft state must persist across app suspensions using the storage adapter layer — the draft model should store all form fields including route strings, distance, and calculated amount. Edge cases: zero-distance entry, rate unavailable, threshold exactly met, and conflicting draft from a previous incomplete session. Integration with the expense list component must display the correct status badge (auto-approved vs. pending) immediately after submission response.
Acceptance Criteria
- Given I open the expense registration screen, when I select 'Mileage' as the expense type, then the mileage entry form is displayed with route input fields and a real-time reimbursement preview
- Given I enter a distance, when the organizational rate is loaded, then the total reimbursement amount is calculated and displayed immediately without requiring a manual submit
- Given the distance is below the auto-approval threshold and no other expenses are attached, when I submit, then the claim is automatically approved and I receive a confirmation
- Given the distance exceeds the auto-approval threshold, when I submit, then the claim is routed to a coordinator for manual review and I see a 'Pending Approval' status
- Given I leave the form mid-completion, when I return, then previously entered data is preserved via draft state
- Given the organizational rate has been configured in the admin portal, when I view the reimbursement preview, then the displayed rate matches the current org-specific rate
Business Value
Mileage reimbursement is the most common expense claim for peer mentors. Automating calculation and enabling auto-approval for small claims eliminates the administrative burden on both mentors and coordinators, directly reducing underreporting caused by friction. This increases the accuracy of activity data used for Bufdir reporting and ensures volunteers feel fairly compensated, improving retention.
Components
- Expense Registration Screen ui
- Expense Type Picker Widget ui
- Expense Calculation Preview ui
- Expense Selection BLoC service
- 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 Form BLoC service
- Expense Validation Service service
- Expense Submission Service service
- Expense Threshold Configuration infrastructure