Organization Hierarchy
Data Entity
Description
Represents the parent-child relationships between organizations to support multi-tier organizational structures (e.g. NHF's national federation containing 12 subordinate associations, 9 regions, and 1,400 local chapters). Each row links a child organization to its parent, with hierarchy_level and path metadata enabling efficient ancestor/descendant queries and aggregated reporting up the tree.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key for the hierarchy edge record | PKrequiredunique |
organization_id |
uuid |
Foreign key to the child organization in the hierarchy edge | required |
parent_organization_id |
uuid |
Foreign key to the parent organization. Null indicates a root-level organization (no parent). | - |
hierarchy_level |
integer |
Depth in the tree starting at 0 for root organizations (e.g. national federation), 1 for regional, 2 for local chapter. | required |
hierarchy_type |
enum |
Classification of the organizational tier for display, reporting, and aggregation logic. | required |
path |
text |
Materialized path of ancestor organization IDs separated by '/' for efficient subtree queries (e.g. '/nhf-root/region-vest/lokallag-bergen'). | required |
display_order |
integer |
Sort order for displaying sibling organizations under the same parent. | - |
inherits_settings |
boolean |
Whether this organization inherits feature toggles, terminology, and approval rules from its parent unless explicitly overridden. | required |
inherits_modules |
boolean |
Whether the enabled module set is inherited from the parent organization. | required |
aggregates_reporting |
boolean |
Whether activity, expense, and Bufdir reporting roll up from this organization to the parent. | required |
is_active |
boolean |
Soft-delete flag. Inactive hierarchy edges are hidden from navigation but preserved for historical reporting. | required |
metadata |
json |
Flexible per-edge metadata: contact persons, regional codes, Bufdir reporting unit IDs, etc. | - |
created_at |
datetime |
Timestamp when the hierarchy edge was created. | required |
updated_at |
datetime |
Timestamp of the last modification to this hierarchy edge. | required |
created_by |
uuid |
User ID of the admin who created the hierarchy edge. | - |
Database Indexes
idx_organization_hierarchy_org_id
Columns: organization_id
idx_organization_hierarchy_parent
Columns: parent_organization_id
idx_organization_hierarchy_path
Columns: path
idx_organization_hierarchy_level
Columns: hierarchy_level, hierarchy_type
idx_organization_hierarchy_active
Columns: is_active, parent_organization_id
Validation Rules
organization_id_exists
error
Validation failed
parent_organization_id_exists
error
Validation failed
no_self_reference
error
Validation failed
hierarchy_level_matches_path
error
Validation failed
max_depth
error
Validation failed
path_format
error
Validation failed
hierarchy_type_valid
error
Validation failed
unique_org_edge
error
Validation failed
Business Rules
no_circular_hierarchy
An organization cannot be its own ancestor; cycles in the parent chain are forbidden.
single_parent_per_org
Each organization has at most one parent (single-parent tree, not DAG). Multi-org membership for users is handled via member_associations, not via multiple parents.
settings_inheritance_cascade
When inherits_settings is true, child organizations inherit feature toggles, terminology, and approval rules from the nearest ancestor with explicit values.
reporting_rollup
When aggregates_reporting is true, KPIs, team reports, and Bufdir reports for the parent include data from all descendant organizations.
tenant_isolation_within_subtree
Org Admins of a parent organization may view aggregated data of descendants only if the descendant has not opted out via aggregates_reporting=false.
delete_requires_no_descendants
A hierarchy edge cannot be deleted while active descendant organizations exist; admin must reassign or deactivate descendants first.
audit_hierarchy_changes
All create, update, and delete operations on hierarchy edges produce audit log entries because they affect data visibility scope across multiple organizations.