Spaces:
Paused
Paused
| title: Architecture | |
| summary: Stack overview, request flow, and adapter model | |
| Paperclip is a monorepo with four main layers. | |
| ## Stack Overview | |
| ``` | |
| ┌─────────────────────────────────────┐ | |
| │ React UI (Vite) │ | |
| │ Dashboard, org management, tasks │ | |
| ├─────────────────────────────────────┤ | |
| │ Express.js REST API (Node.js) │ | |
| │ Routes, services, auth, adapters │ | |
| ├─────────────────────────────────────┤ | |
| │ PostgreSQL (Drizzle ORM) │ | |
| │ Schema, migrations, embedded mode │ | |
| ├─────────────────────────────────────┤ | |
| │ Adapters │ | |
| │ Claude Local, Codex Local, │ | |
| │ Process, HTTP │ | |
| └─────────────────────────────────────┘ | |
| ``` | |
| ## Technology Stack | |
| | Layer | Technology | | |
| |-------|-----------| | |
| | Frontend | React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query | | |
| | Backend | Node.js 20+, Express.js 5, TypeScript | | |
| | Database | PostgreSQL 17 (or embedded PGlite), Drizzle ORM | | |
| | Auth | Better Auth (sessions + API keys) | | |
| | Adapters | Claude Code CLI, Codex CLI, shell process, HTTP webhook | | |
| | Package manager | pnpm 9 with workspaces | | |
| ## Repository Structure | |
| ``` | |
| paperclip/ | |
| ├── ui/ # React frontend | |
| │ ├── src/pages/ # Route pages | |
| │ ├── src/components/ # React components | |
| │ ├── src/api/ # API client | |
| │ └── src/context/ # React context providers | |
| │ | |
| ├── server/ # Express.js API | |
| │ ├── src/routes/ # REST endpoints | |
| │ ├── src/services/ # Business logic | |
| │ ├── src/adapters/ # Agent execution adapters | |
| │ └── src/middleware/ # Auth, logging | |
| │ | |
| ├── packages/ | |
| │ ├── db/ # Drizzle schema + migrations | |
| │ ├── shared/ # API types, constants, validators | |
| │ ├── adapter-utils/ # Adapter interfaces and helpers | |
| │ └── adapters/ | |
| │ ├── claude-local/ # Claude Code adapter | |
| │ └── codex-local/ # OpenAI Codex adapter | |
| │ | |
| ├── skills/ # Agent skills | |
| │ └── paperclip/ # Core Paperclip skill (heartbeat protocol) | |
| │ | |
| ├── cli/ # CLI client | |
| │ └── src/ # Setup and control-plane commands | |
| │ | |
| └── doc/ # Internal documentation | |
| ``` | |
| ## Request Flow | |
| When a heartbeat fires: | |
| 1. **Trigger** — Scheduler, manual invoke, or event (assignment, mention) triggers a heartbeat | |
| 2. **Adapter invocation** — Server calls the configured adapter's `execute()` function | |
| 3. **Agent process** — Adapter spawns the agent (e.g. Claude Code CLI) with Paperclip env vars and a prompt | |
| 4. **Agent work** — The agent calls Paperclip's REST API to check assignments, checkout tasks, do work, and update status | |
| 5. **Result capture** — Adapter captures stdout, parses usage/cost data, extracts session state | |
| 6. **Run record** — Server records the run result, costs, and any session state for next heartbeat | |
| ## Adapter Model | |
| Adapters are the bridge between Paperclip and agent runtimes. Each adapter is a package with three modules: | |
| - **Server module** — `execute()` function that spawns/calls the agent, plus environment diagnostics | |
| - **UI module** — stdout parser for the run viewer, config form fields for agent creation | |
| - **CLI module** — terminal formatter for `paperclipai run --watch` | |
| Built-in adapters: `claude_local`, `codex_local`, `process`, `http`. You can create custom adapters for any runtime. | |
| ## Key Design Decisions | |
| - **Control plane, not execution plane** — Paperclip orchestrates agents; it doesn't run them | |
| - **Company-scoped** — all entities belong to exactly one company; strict data boundaries | |
| - **Single-assignee tasks** — atomic checkout prevents concurrent work on the same task | |
| - **Adapter-agnostic** — any runtime that can call an HTTP API works as an agent | |
| - **Embedded by default** — zero-config local mode with embedded PostgreSQL | |