Organization Structure Management
Feature Detail
Description
This feature models and manages the full hierarchical structure of member organizations, from national associations at the top level down through regions to local associations (lokallag). It supports NHF's particularly complex structure of 12 national associations, 9 regions, and 1,400 local associations, as well as the simpler structures of Blindeforbundet and HLF. The feature also handles the distribution and attribution of activities across organizational levels, ensuring that reporting roll-ups are accurate and that each tier's contributions are correctly counted for Bufdir reporting purposes.
Analysis
Accurate organizational hierarchy management is the structural foundation that every other feature depends upon. Without it, role-based access control cannot function correctly, Bufdir reporting cannot aggregate data at the right levels, and coordinators cannot be assigned to the correct groups of peer mentors. For NHF with its 1,400 lokallag, the ability to manage and navigate this structure programmatically rather than through spreadsheets represents a massive operational improvement. The activity distribution logic across organizational levels also ensures that national, regional, and local contributions are transparently tracked, supporting equitable resource allocation and grant justification.
The database schema uses four linked tables: organizations (top-level umbrella), national_associations, regions, and local_associations with foreign key relationships forming the hierarchy. The Organization Tree Screen renders this hierarchy using a recursive Flutter widget, likely a TreeView or custom expandable list. Org Structure Service provides CRUD operations with cascade validation to prevent orphaned nodes. Admin-level Supabase RLS policies gate write access to hierarchy changes. Activity attribution logic in the reporting pipeline must walk the hierarchy upward to aggregate counts at each level. The feature should support bulk import of organizational structure from CSV for initial setup, reducing manual data entry for large organizations like NHF.
Dependencies
Definition of Done
Components (8)
User Stories (15)
As a As an administrator
I want I want organization structure management to be accessible from the Admin Portal dashboard with a clear navigation entry point
So that So that I can reach the hierarchy tools without needing to know a direct URL, and the admin portal provides a coherent entry point for all organizational configuration tasks
- Given I am an authenticated administrator on the Admin Dashboard, when I look for organization management options, then I see a clearly labeled entry for Organization Structure with a summary of unit counts
- Given I tap the Organization Structure entry in the admin portal, when the navigation completes, then I am taken directly to the Organization Tree Screen showing my organization's hierarchy
- Given I am a Global Administrator, when I access the organization structure section, then I have the ability to switch organizational context to view any member organization's hierarchy
- +1 more
As a As an administrator
I want I want to delete an organizational unit with the system preventing deletion of units that still have child nodes or active members assigned
So that So that the organizational hierarchy remains consistent and no data is orphaned by accidental structural removals
- Given I am an authorized administrator, when I tap the Delete action on a unit detail screen, then a confirmation dialog appears before any data is modified
- Given a unit has child associations, when I attempt to confirm deletion, then the system rejects it with an error message listing the child units that must be removed first
- Given a unit has active coordinators assigned, when I attempt to delete it, then the system rejects the deletion and prompts me to reassign or remove those coordinators first
- +2 more
As a As an administrator
I want I want organization structure management to be accessible from the Admin Portal dashboard with a clear navigation entry point
So that So that I can reach the hierarchy tools without needing to know a direct URL, and the admin portal provides a coherent entry point for all organizational configuration tasks
- Given I am an authenticated administrator on the Admin Dashboard, when I look for organization management options, then I see a clearly labeled entry for Organization Structure with a summary of unit counts
- Given I tap the Organization Structure entry in the admin portal, when the navigation completes, then I am taken directly to the Organization Tree Screen showing my organization's hierarchy
- Given I am a Global Administrator, when I access the organization structure section, then I have the ability to switch organizational context to view any member organization's hierarchy
- +1 more
As a As an administrator
I want I want to delete an organizational unit with the system preventing deletion of units that still have child nodes or active members assigned
So that So that the organizational hierarchy remains consistent and no data is orphaned by accidental structural removals
- Given I am an authorized administrator, when I tap the Delete action on a unit detail screen, then a confirmation dialog appears before any data is modified
- Given a unit has child associations, when I attempt to confirm deletion, then the system rejects it with an error message listing the child units that must be removed first
- Given a unit has active coordinators assigned, when I attempt to delete it, then the system rejects the deletion and prompts me to reassign or remove those coordinators first
- +2 more
As a As a Organization Administrator
I want I want to edit the name and metadata of an existing organizational unit within my organization
So that So that the system reflects official name changes or corrections without requiring a full delete-and-recreate workflow
- Given I am an Organization Administrator viewing a unit detail screen, when I tap the Edit button, then the name field becomes editable in-place
- Given I am editing a unit name, when I clear the name field and attempt to save, then validation prevents saving and shows a required field error
- Given I submit a valid name change, when the update completes, then the tree view and detail screen both reflect the new name immediately without a full page reload
- +2 more
As a As an administrator
I want I want to open a detail view for any organizational unit showing its name, type, parent association, child count, assigned coordinators, and aggregated activity statistics
So that So that I can assess the health and composition of each organizational unit and make informed decisions about structure changes
- Given I tap on an organizational unit in the tree, when the detail screen opens, then I see the unit name, type badge, and its parent association name
- Given I am viewing a regional unit detail, when the screen loads, then I see the count of local associations under it and the list of assigned coordinators
- Given I am viewing a national association detail, when I scroll the activity statistics section, then I see aggregated activity counts attributed to this organizational level
- +2 more
As a As an administrator
I want I want to open a detail view for any organizational unit showing its name, type, parent association, child count, assigned coordinators, and aggregated activity statistics
So that So that I can assess the health and composition of each organizational unit and make informed decisions about structure changes
- Given I tap on an organizational unit in the tree, when the detail screen opens, then I see the unit name, type badge, and its parent association name
- Given I am viewing a regional unit detail, when the screen loads, then I see the count of local associations under it and the list of assigned coordinators
- Given I am viewing a national association detail, when I scroll the activity statistics section, then I see aggregated activity counts attributed to this organizational level
- +2 more
As a As a Global Administrator
I want I want the platform to enforce that only admin-level users can modify the organizational hierarchy while all members can read their own org's structure
So that So that coordinators and peer mentors cannot accidentally or maliciously alter the organizational hierarchy that underpins access control and reporting
- Given a coordinator-role user is authenticated, when they attempt to call any write operation on the org hierarchy via the Org Structure Service, then the Supabase RLS policy blocks the operation and returns a permission denied error
- Given an Organization Administrator is authenticated, when they perform a create or edit operation on a unit within their own organization, then the RLS policy allows the write and the operation succeeds
- Given an Organization Administrator attempts to modify a unit belonging to a different organization, when the RLS policy evaluates the request, then the operation is denied
- +2 more
As a As a Global Administrator
I want I want to upload a CSV file containing the full organizational structure and preview it with validation errors before confirming the import
So that So that large organizations like NHF with 1,400 local associations can be onboarded without hours of manual data entry
- Given I am a Global Administrator on the CSV Import Screen, when I upload a CSV file with the expected column format, then a preview table renders within 3 seconds showing all rows mapped to org type and parent
- Given the CSV contains a local association row with an invalid parent region name, when the preview renders, then that row is highlighted with an error message identifying the invalid parent reference
- Given the preview shows validation errors, when I click Confirm Import without fixing them, then only the valid rows are imported and a summary confirms how many were skipped with reasons
- +3 more
As a As an administrator
I want I want to create a new organizational unit at the correct level in the hierarchy by specifying its name, type, and parent association
So that So that the organization structure reflects current real-world organizational changes such as new local associations being chartered
- Given I am an authorized administrator, when I tap the create action on the tree screen, then a creation form appears with fields for name, type, and parent selection
- Given I am filling the creation form, when I select 'local association' as the type, then the parent selector only shows regions as valid parent options
- Given I attempt to create a local association with a national association as parent, when I submit, then the form shows a validation error explaining the hierarchy constraint
- +3 more
As a As an administrator
I want I want to view the complete organizational hierarchy in an expandable tree view from national associations down to local associations
So that So that I can understand the full organizational structure at a glance and navigate to any level without losing context
- Given I am an authenticated administrator, when I open the Organization Tree Screen, then the top-level national associations are displayed with expand controls
- Given the organization tree is displayed, when I tap a national association node, then it expands to show its regions as child nodes
- Given a region node is expanded, when I tap it, then it collapses back to hide its children
- +3 more
As a As an administrator
I want I want to see activity counts and statistics attributed to each organizational level — local, regional, and national — with correct aggregation rolling up through the hierarchy
So that So that I can verify that activities are counted at the right tier and that Bufdir reporting totals will be accurate before submission
- Given I am viewing a local association detail, when I look at the activity statistics section, then I see the count of activities registered directly under that local association
- Given a region has three local associations each with 50 activities, when I view the region detail's activity statistics, then the total shows 150 activities correctly aggregated
- Given an activity is registered at regional level (not tied to a specific local association), when I view the national association's total, then it includes both local-level and region-level activities without duplication
- +2 more
As a As an administrator
I want I want to create a new organizational unit at the correct level in the hierarchy by specifying its name, type, and parent association
So that So that the organization structure reflects current real-world organizational changes such as new local associations being chartered
- Given I am an authorized administrator, when I tap the create action on the tree screen, then a creation form appears with fields for name, type, and parent selection
- Given I am filling the creation form, when I select 'local association' as the type, then the parent selector only shows regions as valid parent options
- Given I attempt to create a local association with a national association as parent, when I submit, then the form shows a validation error explaining the hierarchy constraint
- +3 more
As a As an administrator
I want I want to view the complete organizational hierarchy in an expandable tree view from national associations down to local associations
So that So that I can understand the full organizational structure at a glance and navigate to any level without losing context
- Given I am an authenticated administrator, when I open the Organization Tree Screen, then the top-level national associations are displayed with expand controls
- Given the organization tree is displayed, when I tap a national association node, then it expands to show its regions as child nodes
- Given a region node is expanded, when I tap it, then it collapses back to hide its children
- +3 more
As a As an administrator
I want I want to see activity counts and statistics attributed to each organizational level — local, regional, and national — with correct aggregation rolling up through the hierarchy
So that So that I can verify that activities are counted at the right tier and that Bufdir reporting totals will be accurate before submission
- Given I am viewing a local association detail, when I look at the activity statistics section, then I see the count of activities registered directly under that local association
- Given a region has three local associations each with 50 activities, when I view the region detail's activity statistics, then the total shows 150 activities correctly aggregated
- Given an activity is registered at regional level (not tied to a specific local association), when I view the national association's total, then it includes both local-level and region-level activities without duplication
- +2 more