# wslyvh/paperweight architecture

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

- Interactive diagram: https://gitdiagram.com/wslyvh/paperweight
- Repository: https://github.com/wslyvh/paperweight

## Overview

Paperweight is a local-first desktop app that scans connected email to inventory accounts and mailing lists, surface breaches and personal data, and support cleanup and privacy requests. Its primary workflow runs from connecting a mailbox through sync and analysis to reviewing results and taking actions; paid access also exposes those capabilities through MCP. The graph includes the documented website breach surface as a secondary capability. Some service-to-analysis and UI-to-main-process wiring is not shown in the excerpts, so those relationships are omitted or marked unverified.

Main entry points: [`src/main/services/account.ts`](https://github.com/wslyvh/paperweight/blob/main/src/main/services/account.ts) (Account service), [`src/mcp/server.ts`](https://github.com/wslyvh/paperweight/blob/main/src/mcp/server.ts) (MCP server), [`src/main/db.ts`](https://github.com/wslyvh/paperweight/blob/main/src/main/db.ts) (Local database), [`analysis/src/index.ts`](https://github.com/wslyvh/paperweight/blob/main/analysis/src/index.ts) (Mail analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["App routes<br/>[App.tsx]"]
  node_settings["Settings and license<br/>[settings.ts]"]
end

subgraph group_mail["Mailbox and analysis"]
  node_account["Account service<br/>[account.ts]"]
  node_providers["Mail providers"]
  node_sync["Sync manager<br/>[sync-manager.ts]"]
  node_analysis_service["Analysis service<br/>[analysis.ts]"]
  node_engine["Mail analysis<br/>[index.ts]"]
  node_pii_detection["PII detectors<br/>[index.ts]"]
  node_classification["Mail classification<br/>[type.ts]"]
  node_unsubscribe_detection["Unsubscribe detection<br/>[unsubscribe.ts]"]
  node_messages["Messages<br/>[messages.ts]"]
  node_db[("Local database<br/>[db.ts]")]
  node_global_db[("Global database<br/>[globalDb.ts]")]
  node_migrations["Schema migrations<br/>[migrations.ts]"]
end

subgraph group_privacy["Privacy actions"]
  node_vendors["Account inventory<br/>[vendors.ts]"]
  node_cases["Privacy cases<br/>[cases.ts]"]
  node_gdpr_actions["GDPR actions<br/>[gdprActions.ts]"]
  node_pii["Personal data<br/>[pii.ts]"]
end

subgraph group_interfaces["External interfaces"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_breach_site["Breach information<br/>[route.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_account -->|"selects provider"| node_providers
node_account -->|"starts sync"| node_sync
node_account -->|"uses"| node_messages
node_account -->|"uses"| node_vendors
node_account -->|"uses"| node_db
node_sync -->|"invokes"| node_analysis_service
node_analysis_service -->|"uses"| node_db
node_analysis_service -->|"uses"| node_vendors
node_engine -->|"detects data"| node_pii_detection
node_engine -->|"classifies mail"| node_classification
node_engine -->|"resolves links"| node_unsubscribe_detection
node_db -->|"configures path"| node_global_db
node_db -->|"runs migrations"| node_migrations
node_mcp -->|"checks license"| node_settings
node_mcp -->|"registers case tools"| node_cases
node_mcp -->|"queries inventory"| node_vendors
node_mcp -->|"queries personal data"| node_pii
node_user -.->|"connects agent"| node_mcp
node_user -->|"checks breach alerts"| node_breach_site

click node_app "https://github.com/wslyvh/paperweight/blob/main/src/renderer/App.tsx"
click node_account "https://github.com/wslyvh/paperweight/blob/main/src/main/services/account.ts"
click node_providers "https://github.com/wslyvh/paperweight/tree/main/src/main/providers"
click node_sync "https://github.com/wslyvh/paperweight/blob/main/src/main/sync-manager.ts"
click node_analysis_service "https://github.com/wslyvh/paperweight/blob/main/src/main/services/analysis.ts"
click node_engine "https://github.com/wslyvh/paperweight/blob/main/analysis/src/index.ts"
click node_pii_detection "https://github.com/wslyvh/paperweight/blob/main/analysis/src/detect/index.ts"
click node_classification "https://github.com/wslyvh/paperweight/blob/main/analysis/src/classify/type.ts"
click node_unsubscribe_detection "https://github.com/wslyvh/paperweight/blob/main/analysis/src/classify/unsubscribe.ts"
click node_vendors "https://github.com/wslyvh/paperweight/blob/main/src/main/services/vendors.ts"
click node_messages "https://github.com/wslyvh/paperweight/blob/main/src/main/services/messages.ts"
click node_cases "https://github.com/wslyvh/paperweight/blob/main/src/main/services/cases.ts"
click node_gdpr_actions "https://github.com/wslyvh/paperweight/blob/main/src/main/services/gdprActions.ts"
click node_pii "https://github.com/wslyvh/paperweight/blob/main/src/main/services/pii.ts"
click node_settings "https://github.com/wslyvh/paperweight/blob/main/src/main/services/settings.ts"
click node_db "https://github.com/wslyvh/paperweight/blob/main/src/main/db.ts"
click node_global_db "https://github.com/wslyvh/paperweight/blob/main/src/main/globalDb.ts"
click node_migrations "https://github.com/wslyvh/paperweight/blob/main/src/main/migrations.ts"
click node_mcp "https://github.com/wslyvh/paperweight/blob/main/src/mcp/server.ts"
click node_breach_site "https://github.com/wslyvh/paperweight/blob/main/website/src/app/api/breaches/route.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_app,node_settings,node_user toneBlue
class node_account,node_providers,node_sync,node_analysis_service,node_engine,node_pii_detection,node_classification,node_unsubscribe_detection,node_messages,node_db,node_global_db,node_migrations toneAmber
class node_vendors,node_cases,node_gdpr_actions,node_pii toneMint
class node_mcp,node_breach_site toneRose
```

## Components

### Desktop experience

- [App routes](https://github.com/wslyvh/paperweight/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Settings and license](https://github.com/wslyvh/paperweight/blob/main/src/main/services/settings.ts): `src/main/services/settings.ts`

### Mailbox and analysis

- [Account service](https://github.com/wslyvh/paperweight/blob/main/src/main/services/account.ts): `src/main/services/account.ts`
- [Mail providers](https://github.com/wslyvh/paperweight/tree/main/src/main/providers): `src/main/providers`
- [Sync manager](https://github.com/wslyvh/paperweight/blob/main/src/main/sync-manager.ts): `src/main/sync-manager.ts`
- [Analysis service](https://github.com/wslyvh/paperweight/blob/main/src/main/services/analysis.ts): `src/main/services/analysis.ts`
- [Mail analysis](https://github.com/wslyvh/paperweight/blob/main/analysis/src/index.ts): `analysis/src/index.ts`
- [PII detectors](https://github.com/wslyvh/paperweight/blob/main/analysis/src/detect/index.ts): `analysis/src/detect/index.ts`
- [Mail classification](https://github.com/wslyvh/paperweight/blob/main/analysis/src/classify/type.ts): `analysis/src/classify/type.ts`
- [Unsubscribe detection](https://github.com/wslyvh/paperweight/blob/main/analysis/src/classify/unsubscribe.ts): `analysis/src/classify/unsubscribe.ts`
- [Messages](https://github.com/wslyvh/paperweight/blob/main/src/main/services/messages.ts): `src/main/services/messages.ts`
- [Local database](https://github.com/wslyvh/paperweight/blob/main/src/main/db.ts): `src/main/db.ts`
- [Global database](https://github.com/wslyvh/paperweight/blob/main/src/main/globalDb.ts): `src/main/globalDb.ts`
- [Schema migrations](https://github.com/wslyvh/paperweight/blob/main/src/main/migrations.ts): `src/main/migrations.ts`

### Privacy actions

- [Account inventory](https://github.com/wslyvh/paperweight/blob/main/src/main/services/vendors.ts): `src/main/services/vendors.ts`
- [Privacy cases](https://github.com/wslyvh/paperweight/blob/main/src/main/services/cases.ts): `src/main/services/cases.ts`
- [GDPR actions](https://github.com/wslyvh/paperweight/blob/main/src/main/services/gdprActions.ts): `src/main/services/gdprActions.ts`
- [Personal data](https://github.com/wslyvh/paperweight/blob/main/src/main/services/pii.ts): `src/main/services/pii.ts`

### External interfaces

- [MCP server](https://github.com/wslyvh/paperweight/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Breach information](https://github.com/wslyvh/paperweight/blob/main/website/src/app/api/breaches/route.ts): `website/src/app/api/breaches/route.ts`

### Other components

- **User**

## Connections

- User → App routes: uses (evidence: `README.md`)
- Account service → Mail providers: selects provider (evidence: `src/main/services/account.ts`)
- Account service → Sync manager: starts sync (evidence: `src/main/services/account.ts`)
- Account service → Messages: uses (evidence: `src/main/services/account.ts`)
- Account service → Account inventory: uses (evidence: `src/main/services/account.ts`)
- Account service → Local database: uses (evidence: `src/main/services/account.ts`)
- Sync manager → Analysis service: invokes (evidence: `src/main/sync-manager.ts`)
- Analysis service → Local database: uses (evidence: `src/main/services/analysis.ts`)
- Analysis service → Account inventory: uses (evidence: `src/main/services/analysis.ts`)
- Mail analysis → PII detectors: detects data (evidence: `analysis/src/index.ts`)
- Mail analysis → Mail classification: classifies mail (evidence: `analysis/src/index.ts`)
- Mail analysis → Unsubscribe detection: resolves links (evidence: `analysis/src/index.ts`)
- Local database → Global database: configures path (evidence: `src/main/db.ts`)
- Local database → Schema migrations: runs migrations (evidence: `src/main/db.ts`)
- MCP server → Settings and license: checks license (evidence: `src/mcp/server.ts`)
- MCP server → Privacy cases: registers case tools
- MCP server → Account inventory: queries inventory
- MCP server → Personal data: queries personal data
- User → MCP server: connects agent (evidence: `README.md`)
- User → Breach information: checks breach alerts (evidence: `README.md`)
