Organization

The Organization module shows company structure: an interactive org chart, a hierarchy list with department tasks, and a separate monthly schedules grid.

---

Routes

Route	View	Description
/organization	Chart (default)	Interactive org chart — By section or Full company
/organization?view=list	List	Expandable cluster → department tree; department tasks drawer
/organization/schedules	Schedules	Monthly employee schedule grid — see Employee schedules

Chart and list share the same org tree API. Schedules use a dedicated page and APIs documented under Employee schedules.

---

API

Method	Path	Auth	Purpose
GET	/v1/organization/tree	Any signed-in user	Full org tree: clusters → departments → employees

Response shape:

• clusters[] — active clusters, sorted A–Z by name
  • id, name, managers[] (employee ids)
  • departments[] — active departments in that cluster, sorted A–Z
    • id, name, managers[]
    • employees[] — active members assigned to the department (cluster/dept managers excluded from member lists)
• directory[] — all active employees for name lookup (includes managers not listed under a department)

Each employee node includes: id, full_name, access_level, job_title, employee_id, image, profile_updated_at, and hire_date (ISO string from employment_data.hire_date).

Implementation: api/app/routers/v1/organization.py.

---

Org chart — display modes

Toggle at the top of the chart panel:

Mode	Purpose
By section	Drill-down: Organization → cluster → department
Full company	Entire org on one canvas — GM → clusters → departments → staff columns

By section (drill-down)

Three levels, navigated by clicking Explore on cluster or department cards (breadcrumb to go back):

1. Organization — General Manager + cluster cards (up to 6 per row)
2. Cluster — Cluster manager(s) + department cards (up to 6 per row)
3. Department — Department manager(s) + member cards (up to 6 per row; extra rows stagger under gaps in the row above)

Card style: Standard vertical cards (photo, name, title, report count).

Zoom: 75%–150% in 12.5% steps; default 100%. Scroll inside the chart panel to zoom; drag the canvas to pan.

Full company

Single canvas showing the divisional layout:

General Manager
  └── Clusters (horizontal row)
        └── Departments per cluster (horizontal row, all depts — no 6-per-row cap)
              └── Staff column per department (vertical stack)

Card style: Compact horizontal cards. Leader cards are wider/taller than member cards so names and role labels stay readable.

Zoom: 50%–200%; default 75% (explore mode — chart is not squeezed to fit the viewport). Drag to pan across the full tree.

---

Hierarchy rules (department staff)

Managers assigned on a cluster or department are shown on the leader/unit card only — they are not duplicated as child member cards.

Within a department, staff are arranged as:

Layer	Who	Notes
Department manager(s)	department_manager ids	Single manager = person card; multiple = unit card with manager avatars
SME	Active employees with access level 2 (not managers)	One SME → members hang below; rare multi-SME → SME row, members under first SME
Members	Everyone else (typically access level 1)	Sorted by hire date (oldest first), then name; no hire date sorts last

Applies in both By section (department level) and Full company (under each department column).

---

Leader labels (full company)

Compact leader cards show role text on the subtitle line:

Role	Example subtitle
General Manager	General Manager
Cluster (single manager)	Cluster Manager · Client Services
Cluster (multiple managers)	Manager names as title; Cluster Manager · {cluster name} as subtitle
Department (single manager)	Department Manager · Customer Service
Department (multiple managers)	Manager names as title; Department Manager · {dept name} as subtitle
SME	SME · {job title}

Member/rep cards show job title only.

---

General Manager node

The GM card is resolved from the employee roster by employee number, configured in the web app env:

VITE_ORG_CHART_GENERAL_MANAGER_EMPLOYEE_ID=<employment_data.employee_id>

Set in web/.env (not committed). Matches employment_data.employee_id or employee_key when that is the canonical id. If unset or not found, a placeholder GM card is shown.

Source: web/src/components/orgChart/orgChartConfig.ts, buildOrgChartTree.ts.

---

Interaction

• Pan — Drag anywhere on the chart canvas (including on cards). Text selection is disabled (user-select: none) so dragging does not highlight names.
• Zoom — Mouse wheel inside the chart panel; +/- controls and reset at bottom-right.
• Explore — By section only: click navigable cluster/department cards. Full company is view-only (no drill links on the canvas).

---

List view

/organization?view=list — expandable hierarchy:

• Clusters and departments with manager names
• Department tasks drawer (view from level 1 in your departments; create/edit per task permissions)
• Structure admin (level 5): create/edit clusters and departments via the same modals as the chart page header

Permissions: Platform & admin § Organization (view_tree, edit_departments, assign_managers, create_cluster_or_department).

---

Source files (chart)

Area	Path
Page shell	web/src/pages/OrganizationPage.tsx
Chart UI	web/src/components/orgChart/OrgChart.tsx
Tree builders	web/src/components/orgChart/buildOrgChartTree.ts
Layout	web/src/components/orgChart/orgChartLayout.ts
Cards	web/src/components/orgChart/OrgChartCard.tsx
Viewport pan/zoom	web/src/components/orgChart/useOrgChartViewport.ts
API	api/app/routers/v1/organization.py

---

Not available yet

Item	Notes
Export org chart as PNG or PDF (current view or entire chart)	Tracked on the Roadmap

When export is available, this guide will describe how to use it.