> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Org Structure — departments, seats & reporting lines

> Every organisation has a shape: departments and teams, the jobs that sit inside them, and who reports to whom.

Every organisation has a shape: departments and teams, the jobs that sit inside them, and who reports to whom. The **Org Structure** screen is where you define that shape, so that the rest of the system — employment contracts, the org chart, reporting lines for approvals, and who can see whose data — can hang off it. Think of it as the skeleton; employees are then attached to it through their employment records.

Org Structure is now **chart-first**: you build and edit the hierarchy directly on a reporting chart of **seats** (the boxes people fill), rather than through separate CRUD tables. The two orthogonal, set-up-once concerns — *role templates* and *visibility rules* — live behind an **Advanced** area.

**You'll find this at:** `/org-structure`

> 📷 *Screenshot: The Org Structure chart — seat cards connected by reporting lines, with the Chart⇄List toggle, "Group by department" switch, "Add seat" and "Advanced" buttons — to be added.*

***

## Before you start

* **Which business am I in?** Seats and departments can be defined at **tenant level** (shared across every business) or scoped to **one business**. The business switcher at the top of the app sets the scope for what you see and create. Tenant-level items (those with no business) are visible everywhere; business-scoped ones only appear for that business.
* **Org Structure is shared across products.** The same structure is used by HR, and by other Hitaji 360 products (Faith360 ministries, Edu360 campuses, Retail360 branches, and so on). That is why role and department categories include options like *Ministry*, *Pastoral* and *Academic* alongside the usual *Department* and *Operations*.
* **Permission needed.** Opening the screen requires `org-structure:read`. With read-only access you can browse the chart and list but the edit controls (Add seat, drag-to-reparent, the inspector's assign/edit actions) are hidden. Creating, editing and deleting need `org-structure:create`, `org-structure:update` and `org-structure:delete` (see Permissions below).

***

## The chart surface

The front door is a **reporting chart**. Each card is a **seat** — a single job slot — showing its role title, the department it belongs to (as a coloured dot), who currently occupies it, and an occupancy badge. Cards are joined top-to-bottom by **reports-to** lines.

| Control                 | What it does                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| **Chart ⇄ List toggle** | Switch between the visual chart and a dense, groupable list of the same seats.                          |
| **Group by department** | Groups seats by their department (in the list) / colours them by department (on the chart).             |
| **Add seat**            | Creates a new top-level seat. Hovering a card also reveals a **+** to add a *report* directly under it. |
| **Advanced**            | Opens role templates and visibility rules (`/org-structure/advanced`).                                  |

> The screen's breadcrumb runs **Home › Settings › Org Structure**, and it is also reachable from **Settings**. It's a configuration screen, so most day-to-day HR users won't touch it once it's set up.

### Reading a seat card

* **Title** — the seat's job title (or its role-template name if no title override is set).
* **Department dot** — a colour that's consistent per department, so you can scan which seats belong together.
* **Occupant** — the person currently in the seat (with "+N" if more than one), or a dashed **"Vacant — assign"**.
* **Occupancy badge** — reads **`occupants / budgeted seats`**: e.g. `1/1 filled`, `Vacant` (no one in it yet), or `3/1 over` when more people are mapped to the seat than its headcount allows. *Occupants* = how many people hold the role right now; *budgeted seats* = the headcount the seat is approved for.

***

## Building the structure on the chart

You no longer manage units, positions and assignments in separate tabs — you do it on the chart:

* **Add a seat / add a report.** Click **Add seat** (top-level) or hover a card and click **+** (a report under it). In the dialog you pick an existing **role** or type a **new one** (the role template is created behind the scenes), pick or **create a department inline**, and set a headcount. The seat is created reporting to the card you added it under.
* **Assign / reassign / vacate a person.** Click any card (or list row) to open the **inspector** on the right. Pick the **person type** (Employee, Auth user, Teacher, School administrator, Faith member, Retail staff) and then pick the **actual person from the live list** — no IDs to copy. *Vacate* ends the current assignment; assigning someone new reassigns the seat. (Employees who hold a seat through their employment record show as **"Via Employment"** and are managed from their contract.)
* **Change who a seat reports to.** **Drag a card onto another** to make it report there — the target highlights with a *"Make this the manager"* hint as you drag — or change **Reports to** in the inspector. A drop that would create a loop is rejected.
* **Edit a seat.** The inspector lets you change the seat's **title**, **headcount** and **reports-to**.
* **Bulk actions.** In the **List** view you can multi-select seats and re-parent them in one go, and filter to **vacant seats** to audit what still needs filling.

Everything you build here is scoped to the business in the switcher, and the chart refreshes as you edit.

***

## The building blocks (the data model behind the chart)

The chart is a friendly surface over the same underlying concepts. You rarely need to think about them directly, but here's what a seat is made of.

### Departments (org units)

A **department** (org unit) is one box of your hierarchy — a department, division, branch, team, ministry or campus. Departments can nest to form a tree. On the chart you create one **inline** while adding a seat; you don't need a separate screen.

Key attributes: **Name**, **Unit type** (Ministry, Department, Division, Campus, Branch, Committee, Team, Cell, Other), optional **Code**, **Parent**, **Business** scope, **Display order** and **Active**.

### Roles (position types)

A **role** (position type) is a reusable template for a kind of job — "Branch Manager", "Accountant" — independent of any one department, and it carries the **rank** used for default reporting lines. When you type a *new role* while adding a seat, a role template is created automatically; you only visit **Advanced → Position Types** to fine-tune them.

Key attributes: **Name**, **Category** (Leadership, Pastoral, Governance, Academic, Finance, Operations, Administrative, Volunteer, Other), **Hierarchy level**, **Reports to (role)**, **Scope type**, **Allowed unit types**, **Is unit owner**, **Active**.

### Seats (positions)

A **seat** (position) is a concrete job slot: a role placed inside a department, with a **headcount**. Employees are ultimately attached to seats. This is the card you see on the chart.

### Occupants (assignments)

An **assignment** records that a person currently holds a seat, with start/optional-end dates. Assignments are how the chart knows whose name goes in which box. For an HR-only setup the position on the **employment record** is the primary source of truth, and these assignments mirror it; the org-structure layer also uses them across other products.

> **Assignments vs. the contract's position:** an employment record already points at a seat and department (its "snapshot" of where the person was hired). The chart's assignments are the org-structure layer's own record of current holders, used across products and for routing. → See [Employment records & contracts](/hr/user/employees/employment-and-contracts).

***

## How reporting lines (and managers) are formed

A person's manager can be determined several ways, from most general to most specific:

1. **Role-level** — the role template's *Reports to (role)*: a default that applies wherever the role is used.
2. **Seat-level** — a seat's *Reports to*, which you set by dragging on the chart or in the inspector; this overrides the role-level line for that specific seat.
3. **Contract-level** — the **manager** named directly on an employment record (and, for leave, an explicit **leave approver**), the most specific of all.

**Seat-derived manager (automatic).** When you assign an **employee** to a seat, Hitaji 360 now looks up the occupant of that seat's **parent** and sets the employee's contract **manager** to that person — so approval routing (e.g. "submitter's manager") always matches what the chart shows. Vacating or re-parenting a seat recomputes the affected people's managers. If a seat's parent is vacant, the manager is left unset. You can still override the manager directly on the contract when the real world doesn't follow the chart.

This layering lets you define a sensible default reporting structure once, then override it case by case.

***

## Advanced — role templates & visibility rules

The **Advanced** area (`/org-structure/advanced`) holds the two concerns the chart deliberately doesn't surface:

### Position Types (role templates)

Tune the role templates created behind the scenes — rename them, set their category/rank, restrict which department types they may be used in, or mark a role as a *unit owner*. See the *Roles* attributes above.

### Visibility Rules

**Visibility rules** are an advanced, fine-grained layer that grants a subject (a seat, a role, an assignment or a specific person) the right to *see* or *act on* a target (a department, a seat, a business or a product).

| Field                   | Notes                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| **Subject**             | Who the rule is about — a seat, role, assignment or person.                                 |
| **Target**              | What they get rights over — a department, seat, business or product.                        |
| **Scope**               | **Self**, **Self and children** (the target plus everything beneath it), or **All tenant**. |
| **Rights**              | One or more of **View**, **View reports**, **View financials**, **Approve**.                |
| **Threshold amount**    | An optional money threshold for approval rights.                                            |
| **Reason / expires at** | An audit note and an optional expiry date.                                                  |

These rules drive things like "this committee chair can view financials for their unit and everything below it" or who appears as an approver when a request is routed. Most organisations can leave this alone until they need that level of control.

***

## How an employment record plugs in

When you create an **employment record** for an employee, you choose:

* the **department** they belong to,
* the **seat** they hold, and
* their **manager** (and optionally a separate **leave approver**).

These are stored on the contract itself (as a snapshot at hire time), so the person is placed inside the structure you built here. From that point on, the [Org chart](/hr/user/employees/org-chart) can draw them in the right box, leave requests route to the right approver, and reports group people by department.

→ See [Adding an employee](/hr/user/employees/create-employee) and [Employment records & contracts](/hr/user/employees/employment-and-contracts).

***

## Org Structure vs. the HR Org Chart

There are now two chart-shaped screens — make sure you're on the right one:

|                   | Org Structure (`/org-structure`)                                                            | HR Org Chart (`/hr/org-chart`)                                                    |
| ----------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Purpose**       | *Edit* the hierarchy — add seats, assign people, set reporting lines, manage roles & rules. | *View* employees as a diagram drawn from their active contracts' reporting lines. |
| **Built from**    | Seats, occupants and reports-to edges you configure.                                        | Employment contracts (manager links) in the selected business.                    |
| **Who uses it**   | Administrators setting things up (needs `org-structure:*`).                                 | Anyone with `hr-employees:read` who wants to see the people chart.                |
| **Read or write** | Read/write configuration (read-only without write scope).                                   | Read-only.                                                                        |

If you want to *change* the shape of the organisation, come to **Org Structure**. If you just want to *see the people chart*, go to the [HR Org chart](/hr/user/employees/org-chart).

***

## Permissions

| Action                                                                  | Permission             |
| ----------------------------------------------------------------------- | ---------------------- |
| View the chart, list, seats, roles and visibility rules                 | `org-structure:read`   |
| Add a seat / assign a person / create a department or role / add a rule | `org-structure:create` |
| Edit a seat, reporting line, role or rule                               | `org-structure:update` |
| Delete any of the above                                                 | `org-structure:delete` |

With only `org-structure:read`, the chart and list are visible but all edit affordances are hidden and mutations are blocked. Platform administrators bypass these checks; ordinary users need the explicit slug.

***

## Related

* [HR Org chart](/hr/user/employees/org-chart) — the read-only people diagram drawn from contracts
* [Adding an employee](/hr/user/employees/create-employee) — placing a person into a seat
* [Employment records & contracts](/hr/user/employees/employment-and-contracts) — how a contract attaches to a department, seat and manager
* [Overview & how HR fits together](/hr/user/getting-started/overview)
* [Accessing HR — businesses, roles & permissions](/hr/user/getting-started/accessing-hr)