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.
User Story
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