Activity Aggregation Service
Component Detail
Description
Runs inside the Supabase Edge Function. Queries all activity records for the given scope and period, groups them by peer mentor, and computes totals per activity type. Handles the full NHF organisational hierarchy (national / region / local chapter roll-ups).
activity-aggregation-service
Summaries
The Activity Aggregation Service is the analytical engine that makes Bufdir reporting possible at scale across the full NHF organisational hierarchy. It answers the core question regulators require: how many activities of each type were delivered, by whom, at which level of the organisation, within the reporting period. Without accurate aggregation, the entire compliance workflow breaks down. By handling national, regional, and local chapter roll-ups automatically, it removes the need for manual data consolidation across organisational boundaries — a process that previously required significant coordinator effort and was prone to double-counting errors.
Reliable aggregation is the foundation of stakeholder trust in the data.
This is a high-complexity backend component running inside the Supabase Edge Function with a direct dependency on the org-hierarchy-resolver. It is a critical path item for the Bufdir export feature; the export service cannot produce valid reports until aggregation is correct and tested. Plan for significant testing effort across all scope levels: local chapter, region, and national. The detectDuplicates logic adds additional complexity and requires test data that includes edge cases with overlapping registrations.
Key risk: incorrect roll-up logic at regional or national level produces incorrect Bufdir submissions, which is a compliance failure. Allocate dedicated QA cycles with realistic multi-level organisational test data before release.
This service is deployed as a module within the Supabase Edge Function runtime (Deno/TypeScript). aggregate(orgId, scopeId, scopeLevel, dateRange) is the primary entry point, resolving the full set of child scope IDs via org-hierarchy-resolver before querying activity records. getMentorBreakdown returns per-mentor totals grouped by activity type for the detailed report sections. getRollupTotals computes aggregate counts across the resolved scope tree.
detectDuplicates(activities) should apply a deterministic deduplication key (e.g., mentor_id + activity_type + date + location) to flag exact-match duplicates before aggregation. Ensure all database queries use indexed columns (org_id, scope_id, activity_date) to prevent full table scans on large activity tables. Write unit tests for roll-up logic with mocked org-hierarchy responses to isolate aggregation correctness from database I/O.
Responsibilities
- Query activities across organisational scope and date range
- Aggregate totals per activity type and peer mentor
- Apply roll-up logic for region and national scopes
- Detect and flag duplicate registrations
Interfaces
aggregate(orgId, scopeId, scopeLevel, dateRange)
getRollupTotals(scopeId, level)
getMentorBreakdown(scopeId, dateRange)
detectDuplicates(activities)
getScopeActivities(scopeId, dateRange)
Relationships
Dependencies (1)
Components this component depends on
Related Data Entities (1)
Data entities managed by this component