Define Export Scope Across Organization Hierarchy

Organizations like NHF have complex hierarchies: 12 national associations, 9 regions, and up to 1,400 local chapters. A coordinator responsible for a regional grant may only be entitled to report activity for their specific region's chapters. The scope selector must render the organization hierarchy and allow the coordinator to select individual units or entire branches. It must also resolve which peer mentors belong to each selected unit to ensure activity is attributed correctly. Multi-org membership (peer mentors affiliated with multiple chapters) must be handled without double-counting participants in the Bufdir participant totals.

HIGH story-bufdir-report-export-coordinator-006 8 pts

Story Points

High

Priority

Bufdir Report Export

Feature

User Story

As a Coordinator

I want to select which organizational units (chapters, regions, local branches) are included in a Bufdir export

So that I can generate reports that correctly reflect the organizational scope of my grant agreement without including activity data from units covered under separate grant applications

Acceptance Criteria

Given the coordinator opens scope selection, when the hierarchy loads, then all organization units they have access to are displayed in a tree structure with checkboxes
Given the coordinator selects a parent node (e.g., a region), when the selection is applied, then all child units under that region are automatically included in scope
Given a peer mentor belongs to multiple chapters within the selected scope, when the export aggregates participants, then that peer mentor is counted only once in the participant total
Given the coordinator deselects a specific chapter, when the export is generated, then activities registered by peer mentors exclusively in that chapter are excluded from the report
Given the coordinator has access to only one chapter, when they open scope selection, then that chapter is pre-selected and the hierarchy selector is simplified to avoid confusion
Given the scope selection is complete, when the coordinator proceeds, then the record count banner updates to reflect only activities within the selected organizational scope

Business Value

Incorrect scope in a Bufdir report — either over-reporting (including units from another grant) or under-reporting (missing entitled units) — is a serious compliance risk. Over-reporting can result in grant repayment demands; under-reporting leaves grant money unclaimed. For NHF with 1,400 local chapters, hierarchical scope selection is essential infrastructure for accurate reporting at every organizational level.

Components

Export Scope Selector ui
Organisation Hierarchy Resolver service
Bufdir Aggregation Service service
Participant Deduplication Service service
Geographic Distribution Service service
Aggregation Query Builder data
Multi-Organization Data Isolator data
Supabase Aggregation RPC Functions infrastructure
Access Scope Service service
Hierarchy Aggregation Service service
Organization Unit Repository data
Hierarchy Cache data

Dependencies

Select Reporting Period with Presets and Custom Date Range critical