Hierarchy Aggregation Service
Component Detail
Description
Rolls activity data upward through the hierarchy tree from local chapter level to regional and national levels. Used by reporting and statistics features to aggregate counts across all descendant nodes of any given unit. Supports the Bufdir reporting requirement for national-level summaries.
hierarchy-aggregation-service
Summaries
The Hierarchy Aggregation Service makes national-level reporting possible by automatically rolling up activity data from hundreds of local chapters through regional and national levels, producing the consolidated statistics required for regulatory submissions to bodies such as Bufdir. Without this component, generating national summaries would require manual data collection from individual chapters — a time-consuming, error-prone process that delays reporting and introduces human error risk. By automating aggregation across the entire organizational tree, the platform enables leadership to view real-time national statistics, supports drill-down from national to regional to local level, and ensures that compliance reports reflect accurate, up-to-date figures without manual intervention. This directly strengthens the organization's credibility and governance posture.
Hierarchy Aggregation Service is a high-complexity shared backend service with dependencies on hierarchy-service and organization-unit-repository. Its delivery depends on the hierarchy tree being fully functional, making it a later-phase component in the implementation sequence. The caching strategy is a significant delivery consideration — cache invalidation triggered by hierarchy-changed events requires reliable event delivery between hierarchy-service and this service; plan for testing event-driven invalidation under load and failure conditions. Aggregation depth configurability (region vs.
national) must be scoped against specific reporting requirements before implementation begins to avoid rework. Performance testing is essential: aggregation queries across large hierarchies with many leaf nodes can be expensive, and query optimization or materialized views may be needed. Coordinate with the reporting and statistics features team to align on the aggregation API contract early.
HierarchyAggregationService traverses the organization_unit tree upward from leaf nodes to compute rolled-up activity counts for any ancestor unit. Its interface includes aggregateActivities(unitId, dateRange), aggregateByLevel(organizationId, level, dateRange), getDescendantActivityCount(unitId), buildAggregationPath(unitId), and invalidateCache(unitId). The core aggregation strategy should leverage hierarchy-service.getDescendants(unitId) to retrieve all descendant unit IDs, then query the activity data store with a bulk .in('unit_id', descendantIds) filter for the given dateRange. For large hierarchies, consider PostgreSQL recursive CTEs or materialized aggregation tables to avoid N+1 traversal patterns.
buildAggregationPath() constructs the ancestor chain for drill-down breakdowns, reusing hierarchy-service.getAncestors(). Cache aggregated results with a unit_id + dateRange composite key; invalidateCache(unitId) must also invalidate all ancestor units in the path, since changing a descendant's count affects every ancestor. Subscribe to hierarchy-changed events from hierarchy-service to trigger cascading invalidation when the tree structure changes. This service is shared across reporting and statistics features — treat its interface as a stable API contract.
Responsibilities
- Aggregate activity counts from leaf nodes up to any ancestor
- Support configurable aggregation depth (e.g., region or national)
- Cache aggregated results with invalidation on hierarchy change
- Provide breakdown by unit level for drill-down reporting
Interfaces
aggregateActivities(unitId, dateRange)
aggregateByLevel(organizationId, level, dateRange)
getDescendantActivityCount(unitId)
buildAggregationPath(unitId)
invalidateCache(unitId)
Relationships
Dependencies (2)
Components this component depends on