Organization

Status: Implemented (API + chart + list + schedules).
Last updated: July 7, 2026

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

---

Planned enhancements

Item	Status
Export org chart as PNG or PDF (current view or entire chart)	Planned — see Roadmap § Organization

When export ships, this page and the Progress report will be updated.