# aronprins/paperclip-desktop architecture

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

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

## Overview

Paperclip Desktop is an Electron shell for the upstream Paperclip product, not the implementation of its agent, governance, or business features. A user launches the app, chooses embedded local mode or a saved/new remote, and reaches the Paperclip UI in a mode-appropriate window. Remote setup validates the origin and checks health/authentication; local mode manages the embedded server and its health. Profiles preserve connection choices, while the shell adds navigation controls and release updates. Some boot and window details were not excerpted, so only documented or indexed relationships are shown.

Main entry points: [`src/main.ts`](https://github.com/aronprins/paperclip-desktop/blob/master/src/main.ts) (Electron main), [`src/connection/preflight.ts`](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/preflight.ts) (Remote preflight), [`src/launcher-html.ts`](https://github.com/aronprins/paperclip-desktop/blob/master/src/launcher-html.ts) (Connection chooser), [`src/updater.ts`](https://github.com/aronprins/paperclip-desktop/blob/master/src/updater.ts) (Auto-updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Desktop shell"]
  node_main["Electron main<br/>[main.ts]"]
  node_launcher["Connection chooser<br/>[launcher-html.ts]"]
  node_preload["Renderer preload"]
  node_navigation["Navigation gestures"]
  node_updater["Auto-updater<br/>[updater.ts]"]
end

subgraph group_connections["Connection management"]
  node_profiles[("Saved profiles<br/>[profiles.ts]")]
  node_validation["URL validation<br/>[validate.ts]"]
  node_preflight["Remote preflight<br/>[preflight.ts]"]
  node_windowpolicy["Window policy<br/>[window-policy.ts]"]
end

subgraph group_runtime["Server runtime"]
  node_health["Local health probe"]
  node_lifecycle["Server lifecycle"]
  node_safety["Data path safety<br/>[runtime-safety.ts]"]
end

subgraph group_upstream["Paperclip product"]
  node_paperclip["Paperclip server and UI"]
  node_remote["Remote Paperclip origin"]
end

node_user(("Desktop user"))
node_releases["GitHub Releases"]

node_user -->|"chooses connection"| node_launcher
node_launcher -->|"sends launcher actions"| node_main
node_main -->|"renders chooser"| node_launcher
node_main -->|"uses profiles"| node_profiles
node_profiles -->|"normalizes URLs"| node_validation
node_main -->|"checks remote"| node_preflight
node_preflight -->|"normalizes origin"| node_validation
node_preflight -->|"checks health and session"| node_remote
node_main -->|"enforces navigation policy"| node_windowpolicy
node_main -->|"probes local server"| node_health
node_main -->|"manages server lifecycle"| node_lifecycle
node_main -->|"checks data paths"| node_safety
node_main -->|"starts embedded product"| node_paperclip
node_paperclip -->|"serves desktop UI"| node_main
node_main -.->|"configures renderer bridge"| node_preload
node_main -->|"uses gesture handling"| node_navigation
node_main -->|"wires updates"| node_updater
node_updater -->|"checks and downloads"| node_releases

click node_main "https://github.com/aronprins/paperclip-desktop/blob/master/src/main.ts"
click node_launcher "https://github.com/aronprins/paperclip-desktop/blob/master/src/launcher-html.ts"
click node_preload "https://github.com/aronprins/paperclip-desktop/blob/master/src/launcher-preload.ts"
click node_navigation "https://github.com/aronprins/paperclip-desktop/blob/master/src/navigation-gestures.ts"
click node_updater "https://github.com/aronprins/paperclip-desktop/blob/master/src/updater.ts"
click node_profiles "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/profiles.ts"
click node_validation "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/validate.ts"
click node_preflight "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/preflight.ts"
click node_windowpolicy "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/window-policy.ts"
click node_health "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/local-server-health.ts"
click node_lifecycle "https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/local-server-lifecycle.ts"
click node_safety "https://github.com/aronprins/paperclip-desktop/blob/master/src/runtime-safety.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_main,node_launcher,node_preload,node_navigation,node_updater,node_user toneBlue
class node_profiles,node_validation,node_preflight,node_windowpolicy toneAmber
class node_health,node_lifecycle,node_safety toneMint
class node_paperclip,node_remote toneRose
class node_releases toneIndigo
```

## Components

### Desktop shell

- [Electron main](https://github.com/aronprins/paperclip-desktop/blob/master/src/main.ts): `src/main.ts`
- [Connection chooser](https://github.com/aronprins/paperclip-desktop/blob/master/src/launcher-html.ts): `src/launcher-html.ts`
- [Renderer preload](https://github.com/aronprins/paperclip-desktop/blob/master/src/launcher-preload.ts): `src/launcher-preload.ts`
- [Navigation gestures](https://github.com/aronprins/paperclip-desktop/blob/master/src/navigation-gestures.ts): `src/navigation-gestures.ts`
- [Auto-updater](https://github.com/aronprins/paperclip-desktop/blob/master/src/updater.ts): `src/updater.ts`

### Connection management

- [Saved profiles](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/profiles.ts): `src/connection/profiles.ts`
- [URL validation](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/validate.ts): `src/connection/validate.ts`
- [Remote preflight](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/preflight.ts): `src/connection/preflight.ts`
- [Window policy](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/window-policy.ts): `src/connection/window-policy.ts`

### Server runtime

- [Local health probe](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/local-server-health.ts): `src/connection/local-server-health.ts`
- [Server lifecycle](https://github.com/aronprins/paperclip-desktop/blob/master/src/connection/local-server-lifecycle.ts): `src/connection/local-server-lifecycle.ts`
- [Data path safety](https://github.com/aronprins/paperclip-desktop/blob/master/src/runtime-safety.ts): `src/runtime-safety.ts`

### Paperclip product

- **Paperclip server and UI**
- **Remote Paperclip origin**

### Other components

- **Desktop user**
- **GitHub Releases**

## Connections

- Desktop user → Connection chooser: chooses connection (evidence: `README.md`)
- Connection chooser → Electron main: sends launcher actions (evidence: `README.md`)
- Electron main → Connection chooser: renders chooser (evidence: `src/main.ts`)
- Electron main → Saved profiles: uses profiles (evidence: `src/main.ts`)
- Saved profiles → URL validation: normalizes URLs (evidence: `src/connection/profiles.ts`)
- Electron main → Remote preflight: checks remote (evidence: `src/main.ts`)
- Remote preflight → URL validation: normalizes origin (evidence: `src/connection/preflight.ts`)
- Remote preflight → Remote Paperclip origin: checks health and session (evidence: `src/connection/preflight.ts`)
- Electron main → Window policy: enforces navigation policy (evidence: `src/main.ts`)
- Electron main → Local health probe: probes local server (evidence: `src/main.ts`)
- Electron main → Server lifecycle: manages server lifecycle (evidence: `src/main.ts`)
- Electron main → Data path safety: checks data paths (evidence: `src/main.ts`)
- Electron main → Paperclip server and UI: starts embedded product (evidence: `README.md`)
- Paperclip server and UI → Electron main: serves desktop UI (evidence: `README.md`)
- Electron main → Renderer preload: configures renderer bridge
- Electron main → Navigation gestures: uses gesture handling (evidence: `src/main.ts`)
- Electron main → Auto-updater: wires updates (evidence: `src/main.ts`)
- Auto-updater → GitHub Releases: checks and downloads (evidence: `README.md`)
