Organisation Hierarchy

Epic summary

The Organisation Hierarchy workspace builds the small, strict tree MedCES uses for administrative containment and access scope.

Tenant
└── Governing organisation (optional)
    └── Institute
        └── Department
            └── Department unit (optional)

Programmes, courses, curricula, faculty, students, and facilities are not hierarchy nodes. External regulators, universities, counselling authorities, and separately owned hospitals also remain outside the tree.

Before you start

The tenant and at least one institute must exist. MedCES supplies the allowed entity types and parent-child combinations. A structural change to a published node requires an impact review and a future or current effective date.

Actors and access

Access source	Access in this epic
Tenant Admin or Governance Registrar role	Creates permitted governing organisations and institutes
Institute Admin	Creates and maintains institute departments
Department Admin	Maintains permitted details for their department and units
Institute member with Organisation Approver role	Approves structural additions and changes
Auditor role	Reconstructs the hierarchy and its approval history for any effective date

What the user does

Screen 1: Hierarchy Tree

The screen shows only the permitted institutional nodes. Selecting a node opens its current details, children, status, and history.

The user can filter by institute, entity type, status, effective date, or code. A separate link opens facilities; facilities are not shown as organisation children.

Screen 2: Add or Edit Entity

Field	Required	Meaning and validation
Entity type	Yes	Governing organisation, institute, department, or department unit
Parent	Yes except tenant root	Must be an allowed parent in the same tenant
Name	Yes	Formal current name
Code	Yes	Stable code unique in its owning scope
Short name	No	Display abbreviation
Clinical or non-clinical	Department only	Classifies the department without changing its hierarchy position
Effective from	Yes	Date on which this version becomes valid
Effective to	No	Used when the node will end
Source and reason	Yes for material changes	Order, approval, or another supporting record
Status	Yes	Draft, Under Review, Published, Suspended, or Archived

The path is generated from stable identifiers. Renaming a department never changes its identifier or historical path.

Screen 3: Structural Change

This screen is used to move, suspend, close, split, or merge a published branch. Before submission it shows:

current and proposed parent;
effective date;
affected descendant nodes;
active role grants at affected scopes;
faculty and unit associations;
programmes, courses, delivery mappings, and reports that reference the node;
actions required before the change can be approved.

The screen never rewrites historical records to the new path.

Screen 4: As-of View and History

The user selects a business date and sees the hierarchy that was valid on that date. The screen shows entity versions, earlier parents and names, approvals, and the users who prepared and approved each change.

Worked example: General Medicine

ABC Medical College creates the General Medicine department beneath the institute. Because the department operates through clinical units, Medicine Unit 1 and Medicine Unit 2 are added beneath it.

ABC Medical College
└── General Medicine
    ├── Medicine Unit 1
    └── Medicine Unit 2

Faculty are assigned to those records later. Wards are allocated through the facility and unit screens. The MBBS programme remains owned by ABC Medical College and connects to General Medicine through course and delivery relationships.

Use case 1: Add a department

As an Institute Admin
I want to add a department beneath my institute
So that academic ownership and department-scoped access use a real organisational record.

Acceptance criteria

The parent is an active institute in the same tenant.
Name, code, classification, effective date, and source are recorded.
The path is generated by MedCES.
A Draft department cannot be selected by published academic records.
Publication triggers access-scope and readiness recalculation.

Use case 2: Add an optional department unit

As a Department Admin
I want to add a real unit beneath my department
So that unit teams, capacity, scheduling, and access can use the correct scope.

Acceptance criteria

Only a department can be the parent of a department unit.
The unit is not required where the department does not operate through units.
The unit cannot see its parent or sibling data through a unit-scoped grant.
Team, location, bed, availability, and teaching-capacity details are completed in Department Units and Clinical Teams.

Use case 3: Reorganise a branch

As a tenant member with Organisation Approver role
I want to approve a dated structural change
So that the current structure changes without erasing the structure used by earlier records.

Acceptance criteria

A node cannot become its own ancestor.
A branch cannot move across tenants.
The impact preview lists dependent access, people, academic, facility-allocation, reporting, and integration records.
Required remediation is completed or attached to the approval.
The old path remains available for dates before the change.

Negative cases and alternate flows

Illegal parent type: Reject the change and explain the valid parent.
Orphaned role grant: Block activation until the grant is ended or moved through Users and Access Assignment.
Protected operational period: Allow a future effective date where immediate change would break active work.

Use case 4: Reconstruct historical hierarchy

As a user with Auditor role
I want to view the hierarchy as of a selected date
So that an earlier access or reporting decision can be explained.

Acceptance criteria

Business-effective date is separate from the time the change was recorded.
Historical names and parents are shown rather than replaced by current values.
Export contains stable entity IDs, path versions, validity, and approval evidence.
The auditor sees only the tenant and institute scope included in their grant.

Business rules

Every tenant has exactly one tenant root.
A governing organisation is optional.
An institute belongs to the tenant and may sit beneath one governing organisation.
A department belongs to one institute.
A department unit, where used, belongs to one department.
One node cannot have two current structural parents.
External relationships never become parent-child links.
Programmes, courses, curricula, people, and facilities never become LTREE nodes.
Structural records that have been used are ended or superseded, not physically deleted.
Department and unit grants never provide sibling access.

Technical design

Conceptual schema

Record	Important fields
`org.entity`	`id`, `tenant_id`, entity type, stable code, current version, status
`org.entity_version`	`entity_id`, name, parent entity, `path ltree`, validity, source, approval
`org.entity_type`	stable type code, permitted parent type, maximum depth, active
`org.structural_change`	change type, current parent, proposed parent, effective date, reason, status
`setup.change_impact`	proposed change, dependent record, effect, required action, resolution

Process-layer responsibilities

Generate stable LTREE labels from entity identifiers.
Validate tenant boundary, parent type, depth, cycles, and overlapping validity.
Calculate descendants only from the version valid for the requested date.
Simulate moves, splits, merges, suspension, and closure before approval.
Preserve historical names, parents, paths, and approvals.
Notify the access service and affected readiness checks after publication.

Success outcome

The institute has a small, accurate hierarchy that can support access, ownership, reporting, and scheduling without mixing programmes, people, facilities, or external authorities into the tree.