Bufdir Aggregation Service
Component Detail
Description
Core orchestration service that triggers and coordinates the full aggregation pipeline for a given organization and reporting period. Invokes Supabase RPC functions, applies deduplication rules, and assembles the final structured metrics object matching Bufdir's official reporting categories.
bufdir-aggregation-service
Summaries
The Bufdir Aggregation Service is the business-critical engine that transforms raw organizational activity data into the official government reporting metrics required by Bufdir. By automating the assembly of structured reporting payloads, this component eliminates weeks of manual data reconciliation work per reporting cycle, directly reducing administrative overhead and the risk of costly submission errors. Accurate, timely Bufdir reporting is a compliance obligation tied to public funding, so failures here carry direct financial consequences. This service ensures that all four partner organizations consistently meet their reporting obligations with verified, deduplicated data that reflects true participant engagement — protecting funding relationships and organizational reputation.
This is the highest-complexity component in the reporting pipeline and should be treated as the critical path item for the Bufdir reporting feature delivery. It has the most dependencies of any single service — six direct dependencies including deduplication, geographic distribution, repository, and data isolation — meaning any delay in those components directly delays integration of this service. Plan for extensive integration testing across all dependent services before considering this component done. Deployment requires backend infrastructure capable of executing multi-stage aggregation pipelines within Supabase RPC constraints.
Budget additional QA time for validating metric mappings against Bufdir's official reporting category specifications, as mapping errors are a high-impact failure mode.
The Bufdir Aggregation Service acts as the top-level orchestrator in the reporting pipeline, invoking downstream services in a defined sequence: it calls the ReportingPeriodService to scope the time window, then triggers the BufdirMetricsRepository for raw data reads via Supabase RPC, passes results through the ParticipantDeduplicationService to eliminate proxy/bulk overlaps, and hands off to GeographicDistributionService for regional breakdowns. The final buildBufdirMetricsPayload() call assembles the typed output object. The mapActivityTypesToBufdirCategories() method requires maintaining a mapping table that must be updated whenever Bufdir revises its category schema — this is the most likely source of future maintenance work. All operations are scoped through MultiOrgDataIsolator to enforce row-level tenant isolation.
High complexity rating reflects the stateful, multi-service orchestration pattern.
Responsibilities
- Orchestrate aggregation across activity, event, and contact data sources
- Map internal activity types to Bufdir's official reporting categories
- Apply proxy/bulk registration deduplication before finalizing counts
- Ensure per-organization data isolation throughout the pipeline
- Assemble final Bufdir metrics payload ready for export
Interfaces
aggregateForOrganization(orgId, reportingPeriod)
getAggregatedMetrics(orgId, periodId)
refreshAggregation(orgId, periodId)
mapActivityTypesToBufdirCategories(activities)
validateMetricsCompleteness(metrics)
getAggregationStatus(orgId, periodId)
buildBufdirMetricsPayload(aggregatedData)
Relationships
Dependencies (6)
Components this component depends on
Dependents (2)
Components that depend on this component