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

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. The OrgNode interface defines five core fields:

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:

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 (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):

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 (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
• Company boundaries prevent cross-company actions regardless of org-chart position

Security rules in 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, this route returns both structured data and pre-rendered graphics:

// 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:

{
  "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 (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 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	Core renderer, OrgNode interface, guessRoleTag, ROLE_ICONS, API endpoint
doc/SPEC.md	Conceptual documentation: reporting ≠ permissions
doc/SPEC-implementation.md	UI route definitions, security rule references
server/src/routes/authz.ts	Generic authorization middleware
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 (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.

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

The guessRoleTag function in 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 and consumed by the board UI at /companies/:id/org.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}