Benefit Calculation Service
Component Detail
Description
Pure client-side service that computes personal and societal benefit metrics from activity inputs and organisation-specific multiplier configuration. No personal data leaves the device. Multipliers such as hourly rate equivalents and health-system cost factors are sourced from the organisation config loaded from Supabase at startup.
benefit-calculation-service
Summaries
The Benefit Calculation Service is the analytical engine that converts raw volunteer activity data into the compelling impact figures displayed to peer mentors. Because all computation happens entirely on-device with no personal data transmitted externally, the organisation eliminates data privacy risk and can credibly assure volunteers, regulators, and funders that volunteer activity data never leaves the device. The configurable multipliers — hourly rate equivalents and health-system cost factors — allow the organisation to tune impact figures to reflect regional economic realities or updated public health research, keeping the reported benefits accurate and defensible to funding bodies without requiring an app release for each adjustment.
The Benefit Calculation Service is a pure, dependency-light business logic component whose only external dependency is the `BenefitMultiplierConfigRepository` (which loads organisation-specific multipliers from Supabase at startup). The primary delivery risk is multiplier data availability: if the Supabase config schema or loading mechanism is not finalised, the service cannot be end-to-end tested with realistic values. Mitigation is to define the `BenefitMultiplierConfig` interface early and stub the repository during service development. Because the service is a pure function with no side effects, it is exceptionally easy to unit test — every calculation method can be covered with table-driven tests in a few hours.
Estimate 1–2 days for implementation and 1 day for thorough unit test coverage.
BenefitCalculationService is a pure Dart class (no Flutter dependency) whose public API consists of four synchronous methods. The top-level `calculate(BenefitCalculationInput, BenefitMultiplierConfig) → BenefitCalculationResult` delegates to three sub-calculations: `calculateHoursSaved(sessions, avgMinutes) → double` (converts session × duration to hours), `calculateTravelCostAvoided(sessions, costPerSession) → double` (multiplies session count by the org-configured per-session travel cost factor), and `calculateHealthSystemOffset(hoursSaved, costPerHour) → double` (applies the health-system cost rate from config). All methods are static or instance-pure with no mutable state, enabling direct instantiation without a DI container. The `BenefitMultiplierConfig` is passed in at call time rather than stored, so the service remains stateless and thread-safe.
Unit testing uses `flutter_test`'s `test()` function with table-driven cases covering zero-input edge cases, fractional rounding, and maximum realistic values. The service has no network, database, or platform channel calls, meaning it is fully testable in a standard Dart VM without a device or emulator.
Responsibilities
- Calculate hours-saved benefit from session count and average duration
- Calculate travel-cost-avoided benefit using organisation multiplier
- Calculate estimated public health system cost offset using configurable rate
- Return a typed BenefitCalculationResult value object
Interfaces
calculate(BenefitCalculationInput input, BenefitMultiplierConfig config) → BenefitCalculationResult
calculateHoursSaved(int sessions, int avgMinutes) → double
calculateTravelCostAvoided(int sessions, double costPerSession) → double
calculateHealthSystemOffset(double hoursSaved, double costPerHour) → double
Relationships
Dependents (3)
Components that depend on this component