Select Expense Types with Mutual Exclusion Rules
HLF has explicitly requested that expense type selection use fixed choices rather than free text, and that the system technically prevent impossible combinations such as selecting both mileage reimbursement and public transit for the same journey. The UI should present expense types clearly, disable incompatible options when one is selected, and show accessible labels that explain why a combination is not allowed. The rule engine must be configurable per organization to accommodate different policies.
User Story
Audience Summaries
This story directly protects HLF's financial integrity and operational efficiency by eliminating invalid expense combinations at the point of entry — before they enter the accounting pipeline. By enforcing mutual exclusion rules (e.g., preventing mileage and public transit from being claimed for the same journey), the organization avoids downstream reconciliation errors, reduces coordinator time spent rejecting and re-processing malformed claims, and strengthens audit readiness. The fixed-category approach also enables reliable data aggregation, which is foundational to accurate Bufdir grant submissions and seamless integrations with Xledger and Dynamics. Configurable rules per organization position this feature as a scalable compliance layer that can serve diverse policy environments, supporting HLF's growth and multi-tenant strategy while minimizing administrative overhead.
This is a high-priority story with moderate-to-high delivery complexity due to three intersecting requirements: a configurable rule engine, a reactive UI with real-time state changes, and full accessibility compliance. The rule engine must support per-organization policy configuration, requiring coordination with whoever manages organization onboarding and admin tooling. The UI must handle disabling logic, tooltips explaining exclusions, and live reimbursement previews — all of which require careful UX specification before development begins. Accessibility acceptance criteria (screen reader announcements for disabled states) add QA scope and necessitate testing with assistive technologies.
Dependencies are relatively self-contained, but integration with the calculation preview service and organization settings store must be confirmed. Plan for at least one round of UAT with HLF coordinators to validate rule configurations match their actual policy.
Implementation requires a three-layer approach: a rule engine, a reactive UI component, and an accessibility layer. The rule engine should be modeled as a configurable set of mutual exclusion groups stored per organization (e.g., in a `expense_type_rules` table or JSON config), loaded at session start. The expense type selector UI must reactively disable incompatible options when a selection is made — this involves managing component state so that selecting one type triggers a rules check and sets conflicting options to a disabled state with accessible tooltip content. Use `aria-disabled` and `aria-describedby` to link disabled options to their explanation text for screen reader compatibility.
The calculation preview must subscribe to the current selection state and recalculate estimates on change. Edge cases to handle: what happens if a previously valid combination becomes invalid after an org policy update mid-session, and how to surface that gracefully. Unit test the rule engine logic separately from the UI, and integration test each acceptance criterion with a representative set of org configurations.
Acceptance Criteria
- Given I open the expense type selector, when the screen loads, then all available expense types for my organization are displayed as selectable options with clear labels
- Given I select 'Mileage reimbursement', when I attempt to also select 'Public transit', then the public transit option is disabled and a tooltip explains the mutual exclusion rule
- Given I select a valid combination (e.g. mileage + parking), when I proceed, then both expense types are included in the claim without error
- Given the mutual exclusion rules are configured per organization, when I register with a different organization, then the applicable rules for that organization are enforced
- Given accessibility mode is active, when I navigate the expense type selector, then all options and their disabled states are announced correctly by screen readers
- Given I select an expense type, when a calculation preview is applicable, then the reimbursement estimate updates immediately
Business Value
Preventing invalid expense combinations at the point of entry eliminates downstream accounting errors and reduces coordinator workload in rejecting and re-processing incorrect claims. Fixed selection categories also enable reliable aggregation and reporting, supporting accurate Bufdir submissions and accounting integrations with Xledger and Dynamics.
Components
- Expense Registration Screen ui
- Expense Type Selector Widget ui
- Expense Type Picker Widget ui
- Expense Selection BLoC service
- Mutual Exclusion Rule Engine service
- Expense Calculation Service service
- Expense Type Accessibility Service service
- Expense Type Repository data
- Expense Type Configuration data
- Expense Form BLoC service
- Expense Type Catalogue Repository data