# arunsanap99/paperclip architecture

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

- Interactive diagram: https://gitdiagram.com/arunsanap99/paperclip
- Repository: https://github.com/arunsanap99/paperclip

## Overview

Paperclip is an AI-agent organization manager: users define company goals, organize agents, assign and govern work, then monitor execution and cost. The principal flow runs from the dashboard through the server to persisted work and agent execution, with results and run history available for review. Separate branches cover approvals and budgets, heartbeat-driven operation, workspaces and recovery, agent skills and evaluation, and extensible adapters and integrations. The README documents these capabilities; source excerpts are limited, so links not directly evidenced there are omitted.

Main entry points: [`server/src/app.ts`](https://github.com/arunsanap99/paperclip/blob/master/server/src/app.ts) (Application server), [`packages/db/src/schema`](https://github.com/arunsanap99/paperclip/tree/master/packages/db/src/schema) (Product data store), [`packages/db/src/schema/agents.ts`](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/agents.ts) (Agent profiles), [`packages/db/src/schema/approvals.ts`](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/approvals.ts) (Approvals and review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Goals and work"]
  node_goals["Goals and alignment<br/>[goals.ts]"]
  node_projects["Projects<br/>[projects.ts]"]
  node_tasks["Tasks and issues<br/>[issues.ts]"]
  node_routines["Routines and pipelines<br/>[routines.ts]"]
end

subgraph group_governance["Organization and governance"]
  node_company["Company and agent org<br/>[companies.ts]"]
  node_agents["Agent profiles<br/>[agents.ts]"]
  node_permissions["Permissions and connections<br/>[tool_access.ts]"]
  node_approvals["Approvals and review<br/>[approvals.ts]"]
end

subgraph group_runtime["Execution runtime"]
  node_heartbeat["Heartbeat lifecycle<br/>[run-lifecycle.ts]"]
  node_runner["Agent runner"]
  node_adapters["Provider adapters"]
  node_workspace["Workspace snapshots"]
  node_restore["Workspace restoration"]
end

subgraph group_platform["Platform and integrations"]
  node_database[("Product data store")]
  node_training["Skills and evaluations"]
  node_integrations["MCP and plugins"]
  node_history["Run history and costs<br/>[heartbeat_runs.ts]"]
end

subgraph group_experience["User experience"]
  node_dashboard["Paperclip dashboard<br/>[App.tsx]"]
  node_server["Application server<br/>[app.ts]"]
end

node_user(("Human user"))
node_agent(("External agent"))

node_user -->|"manages"| node_dashboard
node_dashboard -->|"requests work"| node_server
node_server -.->|"persists state"| node_database
node_server -->|"orchestrates agents"| node_runner
node_runner -->|"uses harnesses"| node_adapters
node_adapters -->|"executes"| node_agent
node_server -.->|"runs heartbeats"| node_heartbeat
node_server -->|"supports review"| node_approvals
node_server -.->|"manages snapshots"| node_workspace
node_server -.->|"restores workspaces"| node_restore
node_server -->|"supports integrations"| node_integrations
node_agents -->|"stores profiles"| node_database
node_company -->|"stores governance"| node_database
node_goals -.->|"stores goals"| node_database
node_projects -->|"stores projects"| node_database
node_tasks -->|"stores tasks"| node_database
node_routines -.->|"stores routines"| node_database
node_permissions -->|"stores access"| node_database
node_approvals -.->|"stores approvals"| node_database
node_heartbeat -.->|"records runs"| node_history
node_training -->|"trains agents"| node_agents
node_server -->|"tracks costs"| node_history

click node_dashboard "https://github.com/arunsanap99/paperclip/blob/master/ui/src/App.tsx"
click node_server "https://github.com/arunsanap99/paperclip/blob/master/server/src/app.ts"
click node_company "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/companies.ts"
click node_agents "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/agents.ts"
click node_permissions "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/tool_access.ts"
click node_goals "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/goals.ts"
click node_projects "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/projects.ts"
click node_tasks "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/issues.ts"
click node_approvals "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/approvals.ts"
click node_routines "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/routines.ts"
click node_database "https://github.com/arunsanap99/paperclip/tree/master/packages/db/src/schema"
click node_heartbeat "https://github.com/arunsanap99/paperclip/blob/master/server/src/services/heartbeat/run-lifecycle.ts"
click node_runner "https://github.com/arunsanap99/paperclip/tree/master/packages/paperclip-runner/src"
click node_adapters "https://github.com/arunsanap99/paperclip/tree/master/packages/adapters"
click node_workspace "https://github.com/arunsanap99/paperclip/blob/master/server/src/services/remote-workspace-snapshot-storage.ts"
click node_restore "https://github.com/arunsanap99/paperclip/blob/master/server/src/services/git-workspace-restoration.ts"
click node_training "https://github.com/arunsanap99/paperclip/tree/master/packages/adapters"
click node_integrations "https://github.com/arunsanap99/paperclip/tree/master/packages/plugins"
click node_history "https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/heartbeat_runs.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_tasks,node_routines,node_user toneBlue
class node_company,node_agents,node_permissions,node_approvals toneAmber
class node_heartbeat,node_runner,node_adapters,node_workspace,node_restore toneMint
class node_database,node_training,node_integrations,node_history toneRose
class node_dashboard,node_server,node_agent toneIndigo
```

## Components

### Goals and work

- [Goals and alignment](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/goals.ts): `packages/db/src/schema/goals.ts`
- [Projects](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/projects.ts): `packages/db/src/schema/projects.ts`
- [Tasks and issues](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/issues.ts): `packages/db/src/schema/issues.ts`
- [Routines and pipelines](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/routines.ts): `packages/db/src/schema/routines.ts`

### Organization and governance

- [Company and agent org](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/companies.ts): `packages/db/src/schema/companies.ts`
- [Agent profiles](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/agents.ts): `packages/db/src/schema/agents.ts`
- [Permissions and connections](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/tool_access.ts): `packages/db/src/schema/tool_access.ts`
- [Approvals and review](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/approvals.ts): `packages/db/src/schema/approvals.ts`

### Execution runtime

- [Heartbeat lifecycle](https://github.com/arunsanap99/paperclip/blob/master/server/src/services/heartbeat/run-lifecycle.ts): `server/src/services/heartbeat/run-lifecycle.ts`
- [Agent runner](https://github.com/arunsanap99/paperclip/tree/master/packages/paperclip-runner/src): `packages/paperclip-runner/src`
- [Provider adapters](https://github.com/arunsanap99/paperclip/tree/master/packages/adapters): `packages/adapters`
- [Workspace snapshots](https://github.com/arunsanap99/paperclip/blob/master/server/src/services/remote-workspace-snapshot-storage.ts): `server/src/services/remote-workspace-snapshot-storage.ts`
- [Workspace restoration](https://github.com/arunsanap99/paperclip/blob/master/server/src/services/git-workspace-restoration.ts): `server/src/services/git-workspace-restoration.ts`

### Platform and integrations

- [Product data store](https://github.com/arunsanap99/paperclip/tree/master/packages/db/src/schema): `packages/db/src/schema`
- [Skills and evaluations](https://github.com/arunsanap99/paperclip/tree/master/packages/adapters): `packages/adapters`
- [MCP and plugins](https://github.com/arunsanap99/paperclip/tree/master/packages/plugins): `packages/plugins`
- [Run history and costs](https://github.com/arunsanap99/paperclip/blob/master/packages/db/src/schema/heartbeat_runs.ts): `packages/db/src/schema/heartbeat_runs.ts`

### User experience

- [Paperclip dashboard](https://github.com/arunsanap99/paperclip/blob/master/ui/src/App.tsx): `ui/src/App.tsx`
- [Application server](https://github.com/arunsanap99/paperclip/blob/master/server/src/app.ts): `server/src/app.ts`

### Other components

- **Human user**
- **External agent**

## Connections

- Human user → Paperclip dashboard: manages (evidence: `README.md`)
- Paperclip dashboard → Application server: requests work (evidence: `README.md`)
- Application server → Product data store: persists state
- Application server → Agent runner: orchestrates agents (evidence: `README.md`)
- Agent runner → Provider adapters: uses harnesses (evidence: `README.md`)
- Provider adapters → External agent: executes (evidence: `README.md`)
- Application server → Heartbeat lifecycle: runs heartbeats
- Application server → Approvals and review: supports review (evidence: `README.md`)
- Application server → Workspace snapshots: manages snapshots
- Application server → Workspace restoration: restores workspaces
- Application server → MCP and plugins: supports integrations (evidence: `README.md`)
- Agent profiles → Product data store: stores profiles (evidence: `packages/db/src/schema/agents.ts`)
- Company and agent org → Product data store: stores governance (evidence: `packages/db/src/schema/companies.ts`)
- Goals and alignment → Product data store: stores goals (evidence: `packages/db/src/schema/issues.ts`)
- Projects → Product data store: stores projects (evidence: `packages/db/src/schema/projects.ts`)
- Tasks and issues → Product data store: stores tasks (evidence: `packages/db/src/schema/issues.ts`)
- Routines and pipelines → Product data store: stores routines (evidence: `packages/db/src/schema/routines.ts`)
- Permissions and connections → Product data store: stores access (evidence: `packages/db/src/schema/projects.ts`)
- Approvals and review → Product data store: stores approvals
- Heartbeat lifecycle → Run history and costs: records runs
- Skills and evaluations → Agent profiles: trains agents (evidence: `README.md`)
- Application server → Run history and costs: tracks costs (evidence: `README.md`)
