Hierarchy Service

Hierarchy Service is a high-complexity, shared backend service with a broad interface surface and deep impact across the application. Because it is shared across multiple features, it sits on the critical path for nearly every team working on organizational functionality. Its dependency on organization-unit-repository means database schema must be finalized before full implementation can proceed. Cycle detection, ancestor/descendant path computation, and hierarchy-changed event emission are non-trivial algorithms that require careful unit testing and integration validation.

Plan for dedicated QA cycles covering edge cases: deep nesting, large sibling counts, concurrent mutations, and move operations that could temporarily violate constraints. Any breaking changes to its interface will cascade across all consumers, so API versioning discipline is essential from the outset.

HierarchyService wraps Supabase queries for a recursive adjacency-list table (organization_units) and enforces domain invariants before and after persistence. The interface includes getHierarchy(organizationId), createUnit(), updateUnit(), deleteUnit(), getAncestors(unitId), getDescendants(unitId), findUnitsByType(), and moveUnit(unitId, newParentId). Ancestor and descendant traversal should use recursive CTEs (WITH RECURSIVE) at the Supabase/PostgreSQL layer for efficiency rather than application-level tree walking. Cycle detection in moveUnit() must validate that the target newParentId is not a descendant of the unit being moved — a graph reachability check.

Depth limits should be configurable per organization type. The hierarchy-changed event emission pattern decouples this service from downstream consumers (cache invalidation, aggregation triggers) and should use a domain event bus or Supabase database triggers for consistency. This is a shared service — maintain strict backward compatibility on all public interface methods.