Skip to main content

Team Hierarchy

Team Hierarchy is a visual organization-chart builder that lets you define and manage the reporting structure of your company.

When you add users to Orbit Resolve, they initially exist as a flat list of accounts. Team Hierarchy solves the problem of "who reports to whom" by letting you visually connect employees to their managers on a drag-and-drop canvas. By defining these relationships, you establish the official chain of command used by approval workflows, timesheets, and performance analytics throughout the product.

Is this the right tool?​

If you aren't sure where you should be making changes, use this guide:

How Team Hierarchy works​

The lifecycle of building your organization's hierarchy is straightforward:

Common tasks​

Looking for something specific? Jump directly to standard workflows:

Understand the screen​

The Team Hierarchy screen is divided into three distinct functional areas:

┌─────────────────────────────────────────────────────────────┐
│ 1. Toolbar (Fullscreen • Layout • Refresh • Analytics)      │
├──────────────────────────────────────────────┬──────────────┤
│                                              │              │
│                                              │ 3. Team      │
│                                              │    Members   │
│ 2. Hierarchy Canvas                          │    Panel     │
│                                              │              │
│    (Drag and drop user cards here)           │ [Search...]  │
│                                              │              │
└──────────────────────────────────────────────┴──────────────┘

📸 Screenshot placeholder: team-hierarchy-overview Capture: The Team Hierarchy screen with 2-3 hierarchy levels visible. Must show: Manager/reportee connections, user cards, Team Members sidebar, Toolbar (Layout, Refresh, Statistics). Suggested caption: Team Hierarchy showing employees and their reporting relationships.

1. Toolbar​

Located at the top, the toolbar gives you control over the view.

  • Fullscreen: Expands the canvas to fill your screen (helpful for large organizations).
  • Layout: Automatically untangles your chart into neat vertical rows.
  • Refresh: Syncs the canvas with the latest data from the server.
  • Analytics: Quick chips showing the total number of users, managers, and reporting levels in the company.

2. Hierarchy Canvas​

The main interactive playground. This infinite canvas displays employees as cards and reporting relationships as connecting lines (arrows). You can click and drag the empty background to pan around, and use your mouse wheel to zoom in and out.

3. Team Members Panel​

A searchable list of every user in your organization pinned to the right side of the screen.

Understanding user cards​

Every employee is represented by a detailed card.

📸 Screenshot placeholder: team-hierarchy-user-card Capture: A single User Card showing the Profile Picture, L(x) badge, Name, Role badge, Direct Reports count, and Project Assignment chips. Suggested caption: A detailed User Card on the hierarchy canvas.

Each card displays:

  • Name & Profile: The user's photo, full name, job title, and email.
  • System Role: A badge indicating their product access level (e.g., Owner, Admin, User).
  • Direct Reports: A count of how many employees report directly to them.
  • Project Assignments: Color-coded chips indicating the projects they belong to. PM (Project Manager) or PL (Project Lead) flags appear if they lead those projects.
  • Hierarchy Level (L-Badge): A small badge in the top right indicating their distance from the top of the company.

What are Hierarchy Levels?​

Levels (L0, L1, L2) are automatically calculated based on the reporting structure:

  • L0: The absolute top of the hierarchy (the Organization Owner). This card features a pulsing star icon.
  • L1: Executives or Department Heads who report directly to L0.
  • L2+: Managers and individual contributors reporting down the chain.

Find a user​

When your organization has hundreds of employees, finding one person on the canvas can be difficult.

Steps

  1. Look at the Team Members Panel on the right.
  2. Type the employee's name or job title into the search bar.
  3. Click their name in the results list.

What happens next The canvas will instantly animate, panning and zooming to place that specific employee's card dead-center on your screen.

Assign an employee to a manager​

🔒 Permission required: org.users.hierarchy.manage
If you do not have this permission, you can visually drag lines on your screen, but the system will block the save and display an error.

Before you start

  • Ensure the employee exists in the system (via Team Management).
  • Ensure you know who their manager should be.

Realistic Example
Sarah is a newly hired Backend Developer. She has been invited to Orbit, so her card exists, but she is floating alone on the canvas. You need to assign her to Alex, the Engineering Manager.

BEFORE

[ Alex - Eng Manager ]      [ Sarah - Backend Dev ]
    (No direct reports)          (No manager)

Steps

  1. Search for "Alex" in the sidebar to locate the manager.
  2. Notice the small connection handle (a dot) at the bottom of Alex's card.
  3. Click and hold this bottom handle, then drag your mouse to create a line.
  4. Drop the line onto the connection handle at the top of Sarah's card.

ACTION

Connect: Bottom of Alex ──────▶ Top of Sarah

AFTER

[ Alex - Eng Manager ]
         │
         ▼
[ Sarah - Backend Dev ]

What happens next Orbit intercepts the connection, securely updates Sarah's profile in the database to mark Alex as her manager, and permanently locks the arrow in place.

How to confirm it worked You will see a solid arrow pointing from Alex to Sarah. Furthermore, Alex's card will instantly update its "Direct Reports" count by +1.

If it doesn't work

  • Error: "Cannot connect a user to themselves" — You accidentally dragged a line from a user's bottom handle to their own top handle.
  • Nothing happens — Ensure you are dragging strictly from the bottom of a manager to the top of an employee. Other combinations are ignored.

Change an employee's manager​

🔒 Permission required: org.users.hierarchy.manage

Changing a manager uses the exact same workflow as assigning a new one.

Steps

  1. Find the employee and find their new manager.
  2. Drag a line from the bottom of the new manager to the top of the employee.

What happens behind the action When you drop the line onto the employee, Orbit detects they already have a manager. It instantly deletes the old reporting line, creates the new reporting line, updates the backend database, and displays a success notification. You do not need to manually delete the old connection first.

Organize the hierarchy​

🔒 Permission required: org.users.hierarchy.manage
If you do not have this permission, you can move cards on your screen for easier reading, but the "Layout" button will be hidden, and your visual changes will disappear when you refresh the page.

As you assign managers and move employees around, the canvas can quickly become a tangled web of crossing lines and overlapping cards.

Steps

  1. Click the Layout button in the top toolbar.

What happens next Orbit's layout engine mathematically analyzes every reporting relationship in your company. It instantly untangles the lines, sorts everyone into perfect horizontal rows based on their hierarchy level (L0, L1, etc.), and ensures no cards overlap.

It then saves these exact X and Y coordinates to the server. From that moment on, anyone in the company who opens the Team Hierarchy page will see your perfectly organized layout.

Troubleshooting​

ProblemPossible reasonWhat to do
An employee is missing from the canvas.Their account hasn't been created yet.Go to Team Management and invite the user to your organization.
I cannot draw a connection line.You are dragging the wrong handles.You must drag exclusively from the bottom handle of a manager to the top handle of the reportee.
The "Layout" button is missing.You lack the management permission.Request an Administrator to grant you a role containing org.users.hierarchy.manage.
My layout changes disappear when I refresh.You lack the management permission.You can view the hierarchy, but your physical card movements are not saved to the server.
I accidentally created a mess of lines.Manual dragging got out of hand.Simply click the Layout button to instantly snap everything back into perfect rows.

What next?​

After establishing your company's reporting structure, you may want to:

Developer Reference​

This section provides technical implementation details for developers maintaining the oo-frontend repository.

  • Route: /org/teamhierarchy renders the <TeamHierarchyPage /> component.
  • Canvas Engine: Built on reactflow (v11). Individual employee cards are rendered using the custom <UserNode /> component.
  • Data Model: The hierarchy is completely driven by a parent-child pointer model on the user record (parent_user_id), not a nested JSON tree.
  • Persistence:
    • Calling organizationHierarchyApi.savePositions() sends an array of { user_id, x, y } coordinates to the backend to persist the global layout state.
    • Calling organizationHierarchyApi.updateUserParent() updates the core reporting relationship.
  • Fallback Layout: If no persisted X/Y coordinates exist on initial load, buildHierarchicalLayout() is triggered locally. It calculates a top-down tree starting at y=100, mathematically spacing cards to prevent visual overlap even when cards grow dynamically in height due to Project Assignment chips.
  • Permissions Guard: The Layout button and the onNodeDragStop event (which triggers coordinate saves) are physically wrapped or guarded by a check for the org.users.hierarchy.manage permission string.

QA Reference​

This section provides critical validation scenarios for test engineers.

  • Circular Dependency Prevention: Attempt to make User A report to User B, and User B report to User A. The frontend UI might attempt to draw the line, but the backend API should strictly reject the circular loop with a clear error payload.
  • Self-Connection: Attempt to draw a connection from a user's bottom handle directly back to their own top handle. The UI should instantly reject this with a toast error: "Cannot connect a user to themselves".
  • Unprivileged Interaction: Log in as a user without org.users.hierarchy.manage. Verify that:
    1. The Layout button is completely absent from the DOM.
    2. Dragging a node across the screen does not fire a POST /api/org/hierarchy/positions network request upon mouse release.
  • Dynamic Node Height Overlap: Locate a user with 5+ project assignment chips (creating a tall card). Press the Layout button. Verify that the layout engine successfully measures this tall card and pushes the entire hierarchy level below it further down the Y-axis to prevent overlapping edges.