US-111: Department & Business Unit Management

1. Story Title

Manage organizational hierarchy (Departments & Business Units)

2. Context / Background

To support the HR module (Org Chart, Reporting Lines) and future workflows (Approvals), the system needs a structured representation of the company's internal hierarchy, not just a flat list of users.

3. User Persona

Primary: Priya – HR Manager / Tenant Admin Secondary: Managers (viewing their depts)

4. Problem Statement

Currently, users belong to a tenant but lack structural organization. There is no way to group employees by function (Engineering, Sales) or location/unit, making reporting and management difficult.

5. Desired Outcome

Admin can define a hierarchical structure of Business Units and Departments. Employees can then be assigned to these entities.

6. Business Value

Foundational for all HR processes (Org Chart, Leave Approvals, Performance Reviews) and provides better reporting insights.

7. Scope (In / Out)

In: CRUD for Business Units, CRUD for Departments, Parent-Child relationships (Department hierarchy), Assigning a Head of Department. Out: Matrix organization support (dotted line reporting - future), visual drag-and-drop org chart editor (view only for now).

8. Acceptance Criteria (BDD)

Scenario: Create a new Department
  Given Priya is on the Organization Structure page
  When she adds a new department "Engineering" under Business Unit "Product"
  Then the department is created
  And it appears in the structure tree

Scenario: Assign Department Head
  Given the "Engineering" department exists
  When Priya selects "Alice" as the Head of Department
  Then Alice is updated as the manager for that node
  And this relationship is reflected in the Org Chart view

Scenario: Delete Department with assigned employees
  Given "Sales" department has 5 active employees
  When Priya attempts to delete "Sales"
  Then the system prevents deletion
  And shows an error "Cannot delete department with active employees. Please reassign them first."

Scenario: Hierarchy validation
  Given a department "Marketing"
  When Priya tries to make "Marketing" a parent of itself
  Then the system blocks the circular reference

9. UX Notes / References

Tree view or nested list for structure. Modal for Add/Edit Department. Simple dropdowns for Parent Department and Head of Department.

10. Data / Domain Model Impact

New Entities: - BusinessUnit (id, name, headId, tenantId) - Department (id, name, parentDepartmentId, businessUnitId, headId, tenantId) - Update User entity to link to departmentId.

11. NFR Touchpoints

• Performance: Tree retrieval < 100ms for typical org sizes (< 1000 nodes).
• Integrity: Prevent orphan records (cascading deletes restricted).

12. Dependencies

US-101 (Tenant), US-102 (Users exist to be assigned as Heads).

13. Risks & Mitigations

Risk	Impact	Probability	Mitigation
Circular dependencies in hierarchy	Infinite loops in logic	Low	Graph cycle detection validation on save
Complex re-orgs (bulk moves)	User frustration	Medium	Bulk edit tools (future); simple one-by-one for MVP

14. Estimation Support

1. Database Schema (Self-referential Dept table)
2. CRUD APIs
3. Tree structure visualization component
4. Validation logic (Circular, Non-empty delete)

15. Analytics / Success Metrics

% of users assigned to a department; depth of hierarchy created.

16. Rollout / Release Strategy

Core feature, release with HR module.

17. Definition of Ready Checklist

• Max hierarchy depth defined (if any)
• Default "Unassigned" department behavior agreed

18. Definition of Done Checklist

• API tests for cycle detection
• UI tree renders correctly
• Employee profile shows Department link

19. Open Questions

1. Do we need "Cost Centers" separate from Departments? (Parked for Finance module).
2. Can a department span multiple Business Units? (No, strict hierarchy for MVP).

---

Version: 1.0