# Paperclip AI Org Chart: Roles, Permissions, and Reporting Lines Explained

> Understand Paperclip AI org chart roles, permissions, and reporting lines. Explore agent hierarchy, role tags for styling, and separate access control for enhanced security.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-12

---

**Paperclip AI implements org chart roles as a hierarchical graph of agents where `role` tags drive visual styling and reporting relationships, while access control is enforced separately through company-boundary security rules.**

In Paperclip, a company is modeled as a **hierarchical graph of agents** defined by the `OrgNode` interface. Each agent carries a `role` that determines its visual representation and position in the reporting structure. This architecture separates organizational hierarchy from permission enforcement—a critical distinction for developers extending the platform.

## Org Node Data Model and Role Normalization

The foundational data structure lives in [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts). The `OrgNode` interface defines five core fields:

```typescript
export interface OrgNode {
  id: string;            // UUID of the agent
  name: string;          // Human-readable name
  role: string;          // Free-form role text (e.g. "Chief Engineer")
  status: string;        // Live run state (idle, running, paused…)
  reports: OrgNode[];    // Direct reports (children)
  collapsedReports?: OrgNode[]; // Internal avatar-grid rendering
}

```

Role strings in Paperclip are **free-form**, meaning agents can declare any title. To ensure consistent UI rendering, the system normalizes arbitrary role text through the `guessRoleTag` function:

```typescript
function guessRoleTag(node: OrgNode): string {
  const name = node.name.toLowerCase();
  const role = node.role.toLowerCase();
  if (name === "ceo" || role.includes("chief executive")) return "ceo";
  if (name === "cto" || role.includes("chief technology")) return "cto";
  // … additional mappings …
  if (role.includes("engineer") || role.includes("eng")) return "engineer";
  // …
  return "default";
}

```

This mapping is **lenient by design**. Variations like "Chief Technology Officer," "CTO," or "Tech Lead" all resolve to canonical tags with associated visual assets. According to the source code in [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts) (lines 38–51), this guarantees that the UI renders known icons even when company-specific role naming conventions differ.

## Visual Themes and Role Icons

Each canonical role tag maps to visual definitions in the `ROLE_ICONS` constant (lines 60–135 of [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts)):

```typescript
const ROLE_ICONS: Record<string, {
  bg: string;               // Card background colour
  roleLabel: string;       // Human-readable label
  accentColor: string;     // Top-bar glow accent
  emojiSvg: string;        // Inline Twemoji SVG paths
  iconPath: string;        // Monochrome fallback path
  iconColor: string;
}> = {
  ceo: { … },
  cto: { … },
  engineer: { … },
  default: { … }
};

```

Paperclip AI org chart themes extend beyond static colors. The `ORG_CHART_STYLES` constant (lines 17–20) defines selectable visual modes: `monochrome`, `nebula`, `circuit`, `warmth`, and `schematic`. Each theme controls gradients, shadows, fonts, and card styling while consuming the same `ROLE_ICONS` definitions.

## Reporting Lines vs. Permission Enforcement

The **reporting hierarchy** exists solely in the `reports` field of each `OrgNode`. The board UI renders this as a tree where children are direct reports. However, as documented in [`doc/SPEC.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC.md) (line 142):

> *"Full visibility across the org. Every agent can see the entire org chart, all tasks, all agents. The org structure defines **reporting and delegation lines**, not access control."*

This separation is architectural:

- **Reporting lines** guide human expectations and delegation workflows
- **Permissions** are enforced by generic authz middleware in [`server/src/routes/authz.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/authz.ts)
- **Company boundaries** prevent cross-company actions regardless of org-chart position

Security rules in [`doc/SPEC-implementation.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC-implementation.md) implement "strict company boundary checks" independent of the org-chart structure. An agent at any level can view the complete chart, but state-modifying actions undergo separate verification.

## API Endpoint and Data Retrieval

The Paperclip AI org chart API exposes the hierarchy through a single endpoint:

```

GET /companies/:companyId/org

```

Implemented in [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts), this route returns both structured data and pre-rendered graphics:

```typescript
// client.ts – Retrieve org chart for company "c123"
import fetch from 'node-fetch';

async function loadOrgChart(companyId: string) {
  const resp = await fetch(
    `http://localhost:3100/api/companies/${companyId}/org`
  );
  if (!resp.ok) throw new Error(`Failed ${resp.status}`);
  const { nodes, svg } = await resp.json();
  console.log('Org chart JSON:', nodes);
  console.log('SVG markup:', svg);
}

loadOrgChart('c123').catch(console.error);

```

Response structure:

```json
{
  "nodes": [
    {
      "id": "a1",
      "name": "Sam",
      "role": "CEO",
      "status": "idle",
      "reports": [
        {
          "id": "a2",
          "name": "Zoe",
          "role": "Engineer",
          "status": "running",
          "reports": []
        }
      ]
    }
  ],
  "svg": "<svg …>…</svg>"
}

```

The board UI route (`/companies/:id/org`) consumes this payload for interactive visualization, as noted in [`doc/SPEC-implementation.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC-implementation.md) (line 76).

## Governance and Write Access Control

While org chart read access is universal within a company, modifications are restricted:

- **Read**: All agents retrieve the complete chart via the public API
- **Write**: Adding agents, removing nodes, or reassigning reports requires company-admin privileges
- **Task delegation**: The task service in [`server/src/services/routines.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/routines.ts) records target `id` values without verifying reporting-line relationships

The org chart **visualizes** hierarchy and **informs** delegation patterns, but **enforcement** remains the responsibility of the broader permission framework.

## Key Source Files

| File | Purpose in Org Chart Architecture |
|---|---|
| [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts) | Core renderer, `OrgNode` interface, `guessRoleTag`, `ROLE_ICONS`, API endpoint |
| [`doc/SPEC.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC.md) | Conceptual documentation: reporting ≠ permissions |
| [`doc/SPEC-implementation.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC-implementation.md) | UI route definitions, security rule references |
| [`server/src/routes/authz.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/authz.ts) | Generic authorization middleware |
| [`server/src/services/routines.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/routines.ts) | Task delegation logic |

## Summary

- **Org nodes** use the `OrgNode` interface with free-form `role` fields normalized by `guessRoleTag`
- **Canonical role tags** (`ceo`, `cto`, `engineer`, etc.) map to visual assets in `ROLE_ICONS`
- **Five visual themes** (`monochrome`, `nebula`, `circuit`, `warmth`, `schematic`) control presentation
- **Reporting lines** in `reports` arrays define hierarchy but do not gate permissions
- **Security enforcement** operates through company-boundary checks separate from org-chart structure
- **Public API** at `/companies/:id/org` yields JSON tree and rendered SVG

## Frequently Asked Questions

### Does the Paperclip AI org chart control who can access what data?

No. According to [`doc/SPEC.md`](https://github.com/paperclipai/paperclip/blob/main/doc/SPEC.md) (line 142), the org chart defines **reporting and delegation lines**, not access control. Every agent can see the entire org chart. Read/write permissions are enforced by separate authz middleware and company-boundary security rules in [`server/src/routes/authz.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/authz.ts).

### How does Paperclip handle non-standard job titles in the org chart?

The `guessRoleTag` function in [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts) (lines 38–51) normalizes arbitrary role strings to canonical tags. It performs case-insensitive substring matching on keywords like "chief executive," "engineer," or "CTO," falling back to `"default"` for unrecognized titles.

### What visual customization options exist for org chart rendering?

Five built-in themes control aesthetics: `monochrome`, `nebula`, `circuit`, `warmth`, and `schematic`. The `ROLE_ICONS` constant defines per-role colors, labels, and SVG assets. Developers can extend `ORG_CHART_STYLES` and `ROLE_ICONS` to add custom themes or role definitions.

### Which API endpoint returns the org chart data and visualization?

`GET /companies/:companyId/org` returns both a machine-readable JSON tree (`nodes`) and a pre-rendered SVG string (`svg`). The route is implemented in [`server/src/routes/org-chart-svg.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/org-chart-svg.ts) and consumed by the board UI at `/companies/:id/org`.