# paperclipai/paperclip architecture

> Architecture diagram of the GitHub repository paperclipai/paperclip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paperclipai/paperclip
- Repository: https://github.com/paperclipai/paperclip
- Video tour (about a minute): https://gitdiagram.com/paperclipai/paperclip/video

## Overview

Paperclip is an application for orchestrating AI-agent organizations. The documented workflow is to define company goals, organize agents and work, approve or govern execution, then monitor results and costs in the UI. Its server, UI, relational domain model, and adapter ecosystem are the main runtime layers. The excerpts show schema responsibilities and selected storage/runtime helpers, but not the server route wiring or most UI/API calls; those links are therefore documented only where the README supports them, and otherwise omitted.

Main entry points: [`server/src/app.ts`](https://github.com/paperclipai/paperclip/blob/master/server/src/app.ts) (Application server), [`server/src/services/heartbeat/run-lifecycle.ts`](https://github.com/paperclipai/paperclip/blob/master/server/src/services/heartbeat/run-lifecycle.ts) (Agent run lifecycle), [`packages/adapters`](https://github.com/paperclipai/paperclip/tree/master/packages/adapters) (Agent adapters), [`ui/src/App.tsx`](https://github.com/paperclipai/paperclip/blob/master/ui/src/App.tsx) (Manage and monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Goals and work"]
  node_goals["Business goals<br/>[goals.ts]"]
  node_projects["Projects<br/>[projects.ts]"]
  node_issues["Tasks and approvals<br/>[issues.ts]"]
  node_pipelines["Workflow pipelines<br/>[pipelines.ts]"]
  node_pipeline_cases["Pipeline cases<br/>[pipeline_cases.ts]"]
  node_history["Activity and run history<br/>[heartbeat_runs.ts]"]
end

subgraph group_governance["Organization and governance"]
  node_companies["Company settings<br/>[companies.ts]"]
  node_agents["Agent roster<br/>[agents.ts]"]
  node_skills["Skills and training"]
  node_budgets["Budgets and costs<br/>[companies.ts]"]
end

subgraph group_runtime["Execution platform"]
  node_server["Application server<br/>[app.ts]"]
  node_heartbeat["Agent run lifecycle<br/>[run-lifecycle.ts]"]
  node_adapters{{"Agent adapters"}}
  node_runner["Agent runner"]
  node_connections["MCP and integrations<br/>[client.ts]"]
  node_storage["Workspace snapshots"]
  node_cli["Setup and operations<br/>[index.ts]"]
end

subgraph group_interface["User interface"]
  node_dashboard["Manage and monitor<br/>[App.tsx]"]
end

subgraph group_state["Persistent state"]
  node_db[("PostgreSQL state<br/>[client.ts]")]
end

node_user(("Human user"))

node_user -->|"sets goals"| node_dashboard
node_dashboard -->|"manages organization"| node_server
node_server -.->|"persists settings"| node_companies
node_server -.->|"manages roster"| node_agents
node_server -.->|"records intent"| node_goals
node_server -.->|"organizes work"| node_projects
node_server -.->|"tracks tasks"| node_issues
node_server -.->|"configures workflows"| node_pipelines
node_server -.->|"tracks cases"| node_pipeline_cases
node_server -.->|"starts agent runs"| node_heartbeat
node_heartbeat -.->|"dispatches runs"| node_adapters
node_adapters -.->|"executes agent work"| node_runner
node_server -.->|"manages training"| node_skills
node_server -.->|"offers integrations"| node_connections
node_server -.->|"enforces cost controls"| node_budgets
node_server -.->|"records run history"| node_history
node_server -->|"stores snapshots"| node_storage
node_server -.->|"reads and writes"| node_db
node_cli -.->|"configures instance"| node_user

click node_dashboard "https://github.com/paperclipai/paperclip/blob/master/ui/src/App.tsx"
click node_server "https://github.com/paperclipai/paperclip/blob/master/server/src/app.ts"
click node_companies "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/companies.ts"
click node_agents "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/agents.ts"
click node_goals "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/goals.ts"
click node_projects "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/projects.ts"
click node_issues "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/issues.ts"
click node_pipelines "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/pipelines.ts"
click node_pipeline_cases "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/pipeline_cases.ts"
click node_heartbeat "https://github.com/paperclipai/paperclip/blob/master/server/src/services/heartbeat/run-lifecycle.ts"
click node_adapters "https://github.com/paperclipai/paperclip/tree/master/packages/adapters"
click node_runner "https://github.com/paperclipai/paperclip/tree/master/packages/paperclip-runner/src"
click node_skills "https://github.com/paperclipai/paperclip/tree/master/server/src"
click node_connections "https://github.com/paperclipai/paperclip/blob/master/packages/mcp-server/src/client.ts"
click node_budgets "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/companies.ts"
click node_history "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/heartbeat_runs.ts"
click node_storage "https://github.com/paperclipai/paperclip/blob/master/server/src/services/remote-workspace-snapshot-storage.ts"
click node_db "https://github.com/paperclipai/paperclip/blob/master/packages/db/src/client.ts"
click node_cli "https://github.com/paperclipai/paperclip/blob/master/cli/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_goals,node_projects,node_issues,node_pipelines,node_pipeline_cases,node_history,node_user toneBlue
class node_companies,node_agents,node_skills,node_budgets toneAmber
class node_server,node_heartbeat,node_adapters,node_runner,node_connections,node_storage,node_cli toneMint
class node_dashboard toneRose
class node_db toneIndigo
```

## Components

### Goals and work

- [Business goals](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/goals.ts): `packages/db/src/schema/goals.ts`
- [Projects](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/projects.ts): `packages/db/src/schema/projects.ts`
- [Tasks and approvals](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/issues.ts): `packages/db/src/schema/issues.ts`
- [Workflow pipelines](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/pipelines.ts): `packages/db/src/schema/pipelines.ts`
- [Pipeline cases](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/pipeline_cases.ts): `packages/db/src/schema/pipeline_cases.ts`
- [Activity and run history](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/heartbeat_runs.ts): `packages/db/src/schema/heartbeat_runs.ts`

### Organization and governance

- [Company settings](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/companies.ts): `packages/db/src/schema/companies.ts`
- [Agent roster](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/agents.ts): `packages/db/src/schema/agents.ts`
- [Skills and training](https://github.com/paperclipai/paperclip/tree/master/server/src): `server/src`
- [Budgets and costs](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/schema/companies.ts): `packages/db/src/schema/companies.ts`

### Execution platform

- [Application server](https://github.com/paperclipai/paperclip/blob/master/server/src/app.ts): `server/src/app.ts`
- [Agent run lifecycle](https://github.com/paperclipai/paperclip/blob/master/server/src/services/heartbeat/run-lifecycle.ts): `server/src/services/heartbeat/run-lifecycle.ts`
- [Agent adapters](https://github.com/paperclipai/paperclip/tree/master/packages/adapters): `packages/adapters`
- [Agent runner](https://github.com/paperclipai/paperclip/tree/master/packages/paperclip-runner/src): `packages/paperclip-runner/src`
- [MCP and integrations](https://github.com/paperclipai/paperclip/blob/master/packages/mcp-server/src/client.ts): `packages/mcp-server/src/client.ts`
- [Workspace snapshots](https://github.com/paperclipai/paperclip/blob/master/server/src/services/remote-workspace-snapshot-storage.ts): `server/src/services/remote-workspace-snapshot-storage.ts`
- [Setup and operations](https://github.com/paperclipai/paperclip/blob/master/cli/src/index.ts): `cli/src/index.ts`

### User interface

- [Manage and monitor](https://github.com/paperclipai/paperclip/blob/master/ui/src/App.tsx): `ui/src/App.tsx`

### Persistent state

- [PostgreSQL state](https://github.com/paperclipai/paperclip/blob/master/packages/db/src/client.ts): `packages/db/src/client.ts`

### Other components

- **Human user**

## Connections

- Human user → Manage and monitor: sets goals (evidence: `README.md`)
- Manage and monitor → Application server: manages organization (evidence: `README.md`)
- Application server → Company settings: persists settings
- Application server → Agent roster: manages roster
- Application server → Business goals: records intent
- Application server → Projects: organizes work
- Application server → Tasks and approvals: tracks tasks
- Application server → Workflow pipelines: configures workflows
- Application server → Pipeline cases: tracks cases
- Application server → Agent run lifecycle: starts agent runs
- Agent run lifecycle → Agent adapters: dispatches runs
- Agent adapters → Agent runner: executes agent work
- Application server → Skills and training: manages training
- Application server → MCP and integrations: offers integrations
- Application server → Budgets and costs: enforces cost controls
- Application server → Activity and run history: records run history
- Application server → Workspace snapshots: stores snapshots (evidence: `server/src/services/remote-workspace-snapshot-storage.ts`)
- Application server → PostgreSQL state: reads and writes
- Setup and operations → Human user: configures instance
