Select Expense Types That Are Mutually Exclusive With Mileage
HLF explicitly requires that the app make mutually exclusive expense combinations technically impossible to select. A peer mentor traveling by car claims mileage; one using public transit claims a transit ticket — never both for the same trip. The expense type picker must enforce mutual exclusion rules defined in the expense type config, using the mutual exclusion rule engine to disable or deselect conflicting options when a primary type is chosen. The expense calculation preview updates to reflect only the selected valid combination.
User Story
Audience Summaries
Enforcing mutual exclusion between mileage and transit expense types at the point of selection eliminates an entire category of invalid reimbursement submissions before they enter the attestation queue. Currently, coordinators must manually identify and reject conflicting expense combinations — a labor-intensive correction loop that delays reimbursement for peer mentors and degrades their volunteer experience. By making invalid combinations technically impossible to select, HLF's financial compliance policies are enforced automatically without depending on volunteers' familiarity with reimbursement rules. This reduces coordinator workload, accelerates reimbursement cycles, and strengthens audit trails — directly supporting volunteer retention and organizational trust in the platform's integrity.
This story requires close collaboration between the product, backend, and frontend teams to implement a dynamic rule engine that reads mutual exclusion configurations from the expense type repository rather than hardcoding logic. The acceptance criteria specify five distinct UI states — disabled options with tooltips, auto-deselection with notifications, field switching between mileage and transit views, and live expense preview updates — each requiring dedicated test cases. A dependency on 'story-mileage-reimbursement-entry-peer-mentor-1' must be resolved before this story can be fully tested end-to-end. UAT should involve coordinators validating that real-world HLF expense policy rules are correctly reflected by the rule engine configuration.
Rollout risk is low if the config-driven approach is validated early.
Implementation requires building or integrating a mutual exclusion rule engine that fetches constraint definitions from the expense type repository on picker load — no hardcoded logic. The expense type picker component must subscribe to selection state changes and evaluate rules reactively: disabling conflicting options with accessible visual indicators (greyed-out + tooltip), or auto-deselecting with a user notification. Field visibility must be driven by selected type (mileage shows route/distance inputs; transit shows ticket fields). The expense calculation preview component must be wired to the valid selection state and recalculate on every change.
Edge cases include switching between types mid-form (clearing stale field values), handling config fetch failures gracefully, and ensuring accessibility compliance on disabled options.
Acceptance Criteria
- Given I select 'mileage reimbursement' as my expense type, When the mutual exclusion rule engine evaluates the selection, Then all public transit ticket options are disabled and visually indicated as unavailable for that trip
- Given I have mileage selected and attempt to also select a transit expense, When the UI renders, Then the conflicting option is either greyed out with an explanatory tooltip or automatically deselected with a notification
- Given I switch from mileage to a public transit expense type, When the selection changes, Then the mileage-specific fields (route input, distance field) are hidden or cleared and replaced with transit-relevant fields
- Given the mutual exclusion rules are defined in the expense type config, When the expense type picker loads, Then it fetches the current rules from the expense type repository and applies them dynamically rather than using hardcoded logic
- Given I have selected a valid, non-conflicting combination of expense types, When I proceed to the calculation preview, Then the expense calculation preview shows the combined total correctly
Business Value
Preventing invalid expense combinations at the UI level eliminates a class of submission errors that currently require coordinator intervention to correct. This directly reduces attestation queue noise, speeds up reimbursement cycles, and enforces HLF's financial compliance policies without relying on user knowledge of reimbursement rules — critical for volunteers with varying familiarity with expense policy.