Annual Stats Aggregation Service
Component Detail
Description
Core business logic service that queries the activity database over a rolling 12-month (or configurable half-year) window for a specific peer mentor and computes summary metrics: total hours, unique contacts helped, sessions by activity type, and streak data. Designed to run both online against Supabase and offline against a local cache.
annual-stats-aggregation-service
Summaries
The Annual Stats Aggregation Service is the analytical engine that transforms raw volunteering activity records into the meaningful metrics that define programme success — total hours contributed, individuals reached, and engagement patterns over time. These metrics are the primary evidence base for grant reporting, stakeholder presentations, and mentor recognition programmes. By supporting both online and offline operation, the service ensures that peer mentors in low-connectivity environments can still access their summaries reliably, removing barriers to engagement and maintaining the quality of data available for programme oversight.
High complexity service with dependencies on annual-summary-repository and milestone-detection-service, both of which must be available before end-to-end testing is possible. The dual online/offline execution requirement introduces significant testing surface area: network transition handling, cache staleness logic, and Supabase query optimisation all require dedicated test coverage. Performance testing against realistic data volumes is essential given the rolling 12-month aggregation window. Plan for integration testing to be sequenced after repository and detection service stabilisation.
Risk of scope creep is moderate — aggregation logic should be strictly bounded to computation, with no UI concerns leaking in.
computeAnnualSummary() orchestrates parallel calls to getTotalHours(), getUniqueContactsHelped(), getActivityTypeBreakdown(), and getMostActiveMonth(), assembling results into an AnnualSummary model. Online mode queries Supabase via annual-summary-repository with date-range filtering on the activity table. Offline mode reads from a local SQLite cache populated during sync. refreshSummary() invalidates the cache and re-fetches from Supabase.
milestone-detection-service is invoked post-computation to evaluate whether new milestones have been crossed. All methods are async and should propagate typed exceptions for network and cache failures. Keep aggregation logic pure and unit-testable by injecting repository dependencies.
Responsibilities
- Aggregate total volunteered hours per peer mentor over the selected period
- Count unique individuals helped across all registered activities
- Compute activity type distribution percentages
- Identify and rank top activity months or periods
Interfaces
computeAnnualSummary(mentorId: String, period: SummaryPeriod): Future<AnnualSummary>
getActivityTypeBreakdown(mentorId: String, period: SummaryPeriod): Future<List<ActivityTypeStat>>
getTotalHours(mentorId: String, period: SummaryPeriod): Future<double>
getUniqueContactsHelped(mentorId: String, period: SummaryPeriod): Future<int>
getMostActiveMonth(mentorId: String, period: SummaryPeriod): Future<DateTime>
refreshSummary(mentorId: String): Future<AnnualSummary>
Relationships
Dependencies (2)
Components this component depends on
Dependents (2)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component