Organisation Hierarchy Navigator
Component Detail
Description
Tree-based navigation component for browsing deeply nested org structures (NHF: national association → region → local chapter) as well as flat structures. Allows admins to scope all data views to a selected node. Supports search within the tree and breadcrumb display of current selection.
org-hierarchy-navigator
Summaries
The Organisation Hierarchy Navigator solves one of the most complex structural challenges in multi-tier membership organisations: giving administrators a clear, navigable view of deeply nested organisational structures — from national associations down through regions to local chapters — without overwhelming them with irrelevant data. By scoping all data views to a selected node, it ensures that administrators only see and act on data within their authority, which is critical for compliance, data privacy, and avoiding accidental cross-organisation changes. Its support for both flat and deeply nested structures also makes the platform viable for a broader range of client organisations, protecting and expanding the addressable market.
High-complexity component with significant delivery risk. The tree rendering and expand/collapse logic must handle arbitrarily deep hierarchies without performance degradation, requiring careful virtualisation or lazy-loading of child nodes. The searchNodes(query) interface adds non-trivial filtering logic that must work across partially loaded trees. Dependencies: org-hierarchy-service must be available with a stable API contract before this component can be integrated or fully tested.
As a shared component, it gates User Account Management Screen and Admin Dashboard Screen delivery. Plan for dedicated performance testing with large org datasets (100+ nodes). Breadcrumb display and getCurrentPath() require consistent state management to stay synchronised with the selected node across navigation events.
OrgHierarchyNavigator is a shared Flutter widget backed by org-hierarchy-service, which should be accessed via an injected repository interface to allow mocking in widget tests. The internal tree state (expanded nodes, current selection, search results) should be managed in a dedicated StateNotifier or ChangeNotifier, not in the widget itself, to enable sharing selection state with parent screens via onNodeSelected(OrgNode node) callbacks. Lazy loading of child nodes on expandNode(nodeId) is strongly recommended for performance; implement a loading placeholder per node. searchNodes(query) should debounce input and filter against an in-memory node list after initial load to avoid excessive API calls.
getCurrentPath() returns the breadcrumb trail as a list of OrgNode — this should be derived from the selection state, not re-fetched. resetToRoot() clears selection and collapses all nodes.
Responsibilities
- Render expandable/collapsible org tree nodes
- Emit selected org node to parent screens for data scoping
- Display breadcrumb trail for current hierarchy position
- Support flat and deeply nested org structures interchangeably
Interfaces
build(context)
onNodeSelected(OrgNode node)
expandNode(nodeId)
collapseNode(nodeId)
searchNodes(query)
getCurrentPath()
resetToRoot()
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component