# nathan7453/paperclip architecture

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

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

## Overview

Paperclip is an open-source control plane for managing teams of AI agents: people define goals, organize agents, assign and review work, and monitor execution and costs. A representative pipeline workflow is visible from the UI or CLI through pipeline APIs and server routes into pipeline services and persisted case data; the UI also presents and edits case documents. The README documents broader capabilities—governance, skills, budgets, and multi-provider execution—that are represented at subsystem level. Some relationships are documented rather than verified in unsampled implementation code.

Main entry points: [`server/src/routes/pipelines.ts`](https://github.com/nathan7453/paperclip/blob/master/server/src/routes/pipelines.ts) (Pipeline routes), [`ui/src/pages/Pipelines.tsx`](https://github.com/nathan7453/paperclip/blob/master/ui/src/pages/Pipelines.tsx) (Pipeline workspace), [`server/src/services/pipelines.ts`](https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipelines.ts) (Pipeline services), [`server/src/services/authorization.ts`](https://github.com/nathan7453/paperclip/blob/master/server/src/services/authorization.ts) (Authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Work orchestration"]
  node_goals["Goals and projects"]
  node_server_route["Pipeline routes<br/>[pipelines.ts]"]
  node_pipeline_service["Pipeline services<br/>[pipelines.ts]"]
  node_pipeline_context["Conversation context"]
  node_case_outputs["Case outputs"]
  node_issue_service["Issue and task service<br/>[issues.ts]"]
end

subgraph group_governance["Organization governance"]
  node_authorization["Authorization<br/>[authorization.ts]"]
  node_source_trust["Source trust<br/>[source-trust.ts]"]
  node_skills["Skills and training"]
  node_budget_cost[("Budgets and costs")]
end

subgraph group_runtime["Agent runtime"]
  node_agent_adapters["Agent adapters"]
end

subgraph group_experience["User interfaces"]
  node_pipeline_ui["Pipeline workspace<br/>[Pipelines.tsx]"]
  node_case_document["Case document editor"]
  node_ui_api["Pipeline API client<br/>[pipelines.ts]"]
  node_cli["Pipeline CLI<br/>[pipelines.ts]"]
end

subgraph group_platform["Shared platform"]
  node_case_store[("Pipeline case records<br/>[pipeline_cases.ts]")]
  node_activity["Activity history<br/>[activity-log.ts]"]
  node_db[("Application database")]
  node_http_client["HTTP client<br/>[client.ts]"]
end

node_person(("Human operator"))

node_person -.->|"defines goals"| node_goals
node_person -.->|"manages work"| node_pipeline_ui
node_person -.->|"runs commands"| node_cli
node_goals -.->|"aligns work"| node_pipeline_ui
node_pipeline_ui -->|"requests pipeline data"| node_ui_api
node_case_document -->|"loads and saves"| node_ui_api
node_ui_api -->|"sends requests"| node_http_client
node_http_client -.->|"calls API"| node_server_route
node_cli -->|"calls pipeline API"| node_server_route
node_server_route -->|"delegates pipeline work"| node_pipeline_service
node_server_route -->|"checks permissions"| node_authorization
node_server_route -->|"records activity"| node_activity
node_server_route -->|"queries cases"| node_case_store
node_pipeline_service -->|"reads and writes"| node_case_store
node_pipeline_service -->|"coordinates issues"| node_issue_service
node_server_route -->|"resolves conversation context"| node_pipeline_context
node_pipeline_context -->|"sanitizes comments"| node_source_trust
node_pipeline_service -->|"uses case outputs"| node_case_outputs
node_source_trust -->|"resolves trust policy"| node_authorization
node_pipeline_ui -.->|"monitors agent work"| node_agent_adapters
node_pipeline_ui -.->|"manages agent training"| node_skills
node_pipeline_ui -.->|"tracks costs"| node_budget_cost
node_agent_adapters -.->|"records run history"| node_db
node_authorization -->|"reads policy data"| node_db
node_activity -->|"persists activity"| node_db

click node_goals "https://github.com/nathan7453/paperclip/tree/master/server/src/services"
click node_pipeline_ui "https://github.com/nathan7453/paperclip/blob/master/ui/src/pages/Pipelines.tsx"
click node_case_document "https://github.com/nathan7453/paperclip/blob/master/ui/src/components/PipelineItemBodyDocument.tsx"
click node_ui_api "https://github.com/nathan7453/paperclip/blob/master/ui/src/api/pipelines.ts"
click node_cli "https://github.com/nathan7453/paperclip/blob/master/cli/src/commands/pipelines.ts"
click node_server_route "https://github.com/nathan7453/paperclip/blob/master/server/src/routes/pipelines.ts"
click node_pipeline_service "https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipelines.ts"
click node_pipeline_context "https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipeline-conversation-context.ts"
click node_case_outputs "https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipeline-case-outputs.ts"
click node_case_store "https://github.com/nathan7453/paperclip/blob/master/packages/db/src/schema/pipeline_cases.ts"
click node_issue_service "https://github.com/nathan7453/paperclip/blob/master/server/src/services/issues.ts"
click node_authorization "https://github.com/nathan7453/paperclip/blob/master/server/src/services/authorization.ts"
click node_source_trust "https://github.com/nathan7453/paperclip/blob/master/server/src/services/source-trust.ts"
click node_activity "https://github.com/nathan7453/paperclip/blob/master/server/src/services/activity-log.ts"
click node_agent_adapters "https://github.com/nathan7453/paperclip/tree/master/packages/adapters"
click node_skills "https://github.com/nathan7453/paperclip/tree/master/packages/shared"
click node_budget_cost "https://github.com/nathan7453/paperclip/tree/master/packages/db/src/schema"
click node_db "https://github.com/nathan7453/paperclip/tree/master/packages/db/src"
click node_http_client "https://github.com/nathan7453/paperclip/blob/master/ui/src/api/client.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_server_route,node_pipeline_service,node_pipeline_context,node_case_outputs,node_issue_service toneBlue
class node_authorization,node_source_trust,node_skills,node_budget_cost toneAmber
class node_agent_adapters toneMint
class node_pipeline_ui,node_case_document,node_ui_api,node_cli toneRose
class node_case_store,node_activity,node_db,node_http_client,node_person toneIndigo
```

## Components

### Work orchestration

- [Goals and projects](https://github.com/nathan7453/paperclip/tree/master/server/src/services): `server/src/services`
- [Pipeline routes](https://github.com/nathan7453/paperclip/blob/master/server/src/routes/pipelines.ts): `server/src/routes/pipelines.ts`
- [Pipeline services](https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipelines.ts): `server/src/services/pipelines.ts`
- [Conversation context](https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipeline-conversation-context.ts): `server/src/services/pipeline-conversation-context.ts`
- [Case outputs](https://github.com/nathan7453/paperclip/blob/master/server/src/services/pipeline-case-outputs.ts): `server/src/services/pipeline-case-outputs.ts`
- [Issue and task service](https://github.com/nathan7453/paperclip/blob/master/server/src/services/issues.ts): `server/src/services/issues.ts`

### Organization governance

- [Authorization](https://github.com/nathan7453/paperclip/blob/master/server/src/services/authorization.ts): `server/src/services/authorization.ts`
- [Source trust](https://github.com/nathan7453/paperclip/blob/master/server/src/services/source-trust.ts): `server/src/services/source-trust.ts`
- [Skills and training](https://github.com/nathan7453/paperclip/tree/master/packages/shared): `packages/shared`
- [Budgets and costs](https://github.com/nathan7453/paperclip/tree/master/packages/db/src/schema): `packages/db/src/schema`

### Agent runtime

- [Agent adapters](https://github.com/nathan7453/paperclip/tree/master/packages/adapters): `packages/adapters`

### User interfaces

- [Pipeline workspace](https://github.com/nathan7453/paperclip/blob/master/ui/src/pages/Pipelines.tsx): `ui/src/pages/Pipelines.tsx`
- [Case document editor](https://github.com/nathan7453/paperclip/blob/master/ui/src/components/PipelineItemBodyDocument.tsx): `ui/src/components/PipelineItemBodyDocument.tsx`
- [Pipeline API client](https://github.com/nathan7453/paperclip/blob/master/ui/src/api/pipelines.ts): `ui/src/api/pipelines.ts`
- [Pipeline CLI](https://github.com/nathan7453/paperclip/blob/master/cli/src/commands/pipelines.ts): `cli/src/commands/pipelines.ts`

### Shared platform

- [Pipeline case records](https://github.com/nathan7453/paperclip/blob/master/packages/db/src/schema/pipeline_cases.ts): `packages/db/src/schema/pipeline_cases.ts`
- [Activity history](https://github.com/nathan7453/paperclip/blob/master/server/src/services/activity-log.ts): `server/src/services/activity-log.ts`
- [Application database](https://github.com/nathan7453/paperclip/tree/master/packages/db/src): `packages/db/src`
- [HTTP client](https://github.com/nathan7453/paperclip/blob/master/ui/src/api/client.ts): `ui/src/api/client.ts`

### Other components

- **Human operator**

## Connections

- Human operator → Goals and projects: defines goals (evidence: `README.md`)
- Human operator → Pipeline workspace: manages work (evidence: `README.md`)
- Human operator → Pipeline CLI: runs commands (evidence: `README.md`)
- Goals and projects → Pipeline workspace: aligns work (evidence: `README.md`)
- Pipeline workspace → Pipeline API client: requests pipeline data (evidence: `ui/src/pages/Pipelines.tsx`)
- Case document editor → Pipeline API client: loads and saves (evidence: `ui/src/components/PipelineItemBodyDocument.tsx`)
- Pipeline API client → HTTP client: sends requests (evidence: `ui/src/api/pipelines.ts`)
- HTTP client → Pipeline routes: calls API (evidence: `README.md`)
- Pipeline CLI → Pipeline routes: calls pipeline API (evidence: `cli/src/commands/pipelines.ts`)
- Pipeline routes → Pipeline services: delegates pipeline work (evidence: `server/src/routes/pipelines.ts`)
- Pipeline routes → Authorization: checks permissions (evidence: `server/src/routes/pipelines.ts`)
- Pipeline routes → Activity history: records activity (evidence: `server/src/routes/pipelines.ts`)
- Pipeline routes → Pipeline case records: queries cases (evidence: `server/src/routes/pipelines.ts`)
- Pipeline services → Pipeline case records: reads and writes (evidence: `server/src/services/pipelines.ts`)
- Pipeline services → Issue and task service: coordinates issues (evidence: `server/src/services/pipelines.ts`)
- Pipeline routes → Conversation context: resolves conversation context (evidence: `server/src/routes/pipelines.ts`)
- Conversation context → Source trust: sanitizes comments (evidence: `server/src/services/pipeline-conversation-context.ts`)
- Pipeline services → Case outputs: uses case outputs (evidence: `server/src/services/pipelines.ts`)
- Source trust → Authorization: resolves trust policy (evidence: `server/src/services/source-trust.ts`)
- Pipeline workspace → Agent adapters: monitors agent work (evidence: `README.md`)
- Pipeline workspace → Skills and training: manages agent training (evidence: `README.md`)
- Pipeline workspace → Budgets and costs: tracks costs (evidence: `README.md`)
- Agent adapters → Application database: records run history (evidence: `README.md`)
- Authorization → Application database: reads policy data (evidence: `server/src/services/authorization.ts`)
- Activity history → Application database: persists activity (evidence: `server/src/services/activity-log.ts`)
