# henno/macos-clipboard-manager architecture

> Architecture diagram of the GitHub repository henno/macos-clipboard-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henno/macos-clipboard-manager
- Repository: https://github.com/henno/macos-clipboard-manager

## Overview

cbm is a macOS clipboard-history app. Its main workflow monitors the pasteboard, filters and preserves clipboard representations, stores history, then lets the user search and preview an entry before restoring it to the clipboard and optionally pasting into the app they left. The graph also shows settings, retention, menu-bar access, and performance measurements. Wiring for unsampled UI and favicon code is limited to capabilities and relationships documented in the README; uncertain links are omitted.

Main entry points: [`Sources/cbm/UI/PanelController.swift`](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/PanelController.swift) (Search panel), [`Sources/cbm/Store/ItemStore.swift`](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/ItemStore.swift) (History store), [`Sources/cbm/UI/SettingsWindowController.swift`](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/SettingsWindowController.swift) (Settings window), [`Sources/cbm/Capture/ClipboardMonitor.swift`](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/ClipboardMonitor.swift) (Clipboard monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_app["App delegate<br/>[AppDelegate.swift]"]
  node_hotkey["Global hotkey<br/>[HotKey.swift]"]
  node_menubar["Menu bar"]
end

subgraph group_capture["Capture and storage"]
  node_monitor["Clipboard monitor"]
  node_reader["Pasteboard reader"]
  node_frontmost["Frontmost tracker"]
  node_itemstore["History store<br/>[ItemStore.swift]"]
  node_db[("SQLite database<br/>[Database.swift]")]
  node_blob[("Blob and thumbnail files<br/>[BlobStore.swift]")]
end

subgraph group_search["Find and preview"]
  node_panel["Search panel"]
  node_index["Search index<br/>[SearchIndex.swift]"]
  node_matcher["Fuzzy matching<br/>[FuzzyMatcher.swift]"]
  node_fold["Text folding<br/>[TextFold.swift]"]
  node_preview["Entry preview<br/>[PreviewView.swift]"]
  node_favicon["Favicon store<br/>[FaviconStore.swift]"]
end

subgraph group_restore["Paste workflow"]
  node_paster["Clipboard restore<br/>[Paster.swift]"]
end

subgraph group_settings["Settings and status"]
  node_settingsui["Settings window"]
  node_settings["Preferences<br/>[Settings.swift]"]
  node_metrics["Live metrics<br/>[Metrics.swift]"]
  node_login["Login item<br/>[LoginItem.swift]"]
end

node_user(("User"))
node_clipboard["macOS pasteboard"]
node_sqlite[("System SQLite")]
node_chrome[("Chrome favicon cache")]
node_target["Previous app"]
node_accessibility["macOS Accessibility"]

node_user -->|"presses shortcut"| node_hotkey
node_app -->|"starts monitoring"| node_monitor
node_app -->|"registers shortcut"| node_hotkey
node_app -->|"installs menu"| node_menubar
node_hotkey -->|"opens panel"| node_panel
node_menubar -->|"opens panel"| node_panel
node_menubar -->|"opens settings"| node_settingsui
node_monitor -->|"checks changes"| node_clipboard
node_monitor -->|"reads changed content"| node_reader
node_reader -->|"submits payload"| node_itemstore
node_monitor -->|"stores payload"| node_itemstore
node_itemstore -->|"reads and writes"| node_db
node_itemstore -->|"stores large payloads"| node_blob
node_db -->|"uses"| node_sqlite
node_panel -->|"polls before opening"| node_monitor
node_panel -->|"queries and updates"| node_index
node_index -->|"scores terms"| node_matcher
node_index -->|"folds query and text"| node_fold
node_panel -->|"shows selection"| node_preview
node_preview -->|"loads full payload"| node_itemstore
node_panel -->|"deletes selection"| node_itemstore
node_panel -->|"restores selection"| node_paster
node_panel -->|"tracks paste target"| node_frontmost
node_frontmost -->|"provides target app"| node_paster
node_paster -->|"writes representations"| node_clipboard
node_paster -->|"activates and pastes"| node_target
node_settingsui -->|"reads and updates"| node_settings
node_settingsui -->|"applies retention and clears"| node_itemstore
node_settingsui -->|"reads measurements"| node_metrics
node_settingsui -->|"configures login"| node_login
node_paster -->|"checks permission"| node_accessibility
node_favicon -.->|"reads copied cache"| node_chrome
node_panel -.->|"warms displayed icons"| node_favicon

click node_app "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/AppDelegate.swift"
click node_hotkey "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/HotKey.swift"
click node_menubar "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/MenuBarController.swift"
click node_monitor "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/ClipboardMonitor.swift"
click node_reader "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/PasteboardReader.swift"
click node_frontmost "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/FrontmostTracker.swift"
click node_itemstore "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/ItemStore.swift"
click node_db "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/Database.swift"
click node_blob "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/BlobStore.swift"
click node_panel "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/PanelController.swift"
click node_index "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/SearchIndex.swift"
click node_matcher "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/FuzzyMatcher.swift"
click node_fold "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/TextFold.swift"
click node_preview "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/PreviewView.swift"
click node_favicon "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/FaviconStore.swift"
click node_paster "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Paste/Paster.swift"
click node_settingsui "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/SettingsWindowController.swift"
click node_settings "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Support/Settings.swift"
click node_metrics "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Support/Metrics.swift"
click node_login "https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/LoginItem.swift"

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_hotkey,node_menubar,node_user toneBlue
class node_monitor,node_reader,node_frontmost,node_itemstore,node_db,node_blob,node_sqlite,node_chrome toneAmber
class node_panel,node_index,node_matcher,node_fold,node_preview,node_favicon toneMint
class node_paster toneRose
class node_settingsui,node_settings,node_metrics,node_login,node_clipboard,node_target,node_accessibility toneIndigo
```

## Components

### App runtime

- [App delegate](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/AppDelegate.swift): `Sources/cbm/AppDelegate.swift`
- [Global hotkey](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/HotKey.swift): `Sources/cbm/UI/HotKey.swift`
- [Menu bar](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/MenuBarController.swift): `Sources/cbm/UI/MenuBarController.swift`

### Capture and storage

- [Clipboard monitor](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/ClipboardMonitor.swift): `Sources/cbm/Capture/ClipboardMonitor.swift`
- [Pasteboard reader](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/PasteboardReader.swift): `Sources/cbm/Capture/PasteboardReader.swift`
- [Frontmost tracker](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Capture/FrontmostTracker.swift): `Sources/cbm/Capture/FrontmostTracker.swift`
- [History store](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/ItemStore.swift): `Sources/cbm/Store/ItemStore.swift`
- [SQLite database](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/Database.swift): `Sources/cbm/Store/Database.swift`
- [Blob and thumbnail files](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Store/BlobStore.swift): `Sources/cbm/Store/BlobStore.swift`

### Find and preview

- [Search panel](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/PanelController.swift): `Sources/cbm/UI/PanelController.swift`
- [Search index](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/SearchIndex.swift): `Sources/cbm/Search/SearchIndex.swift`
- [Fuzzy matching](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/FuzzyMatcher.swift): `Sources/cbm/Search/FuzzyMatcher.swift`
- [Text folding](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Search/TextFold.swift): `Sources/cbm/Search/TextFold.swift`
- [Entry preview](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/PreviewView.swift): `Sources/cbm/UI/PreviewView.swift`
- [Favicon store](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/FaviconStore.swift): `Sources/cbm/UI/FaviconStore.swift`

### Paste workflow

- [Clipboard restore](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Paste/Paster.swift): `Sources/cbm/Paste/Paster.swift`

### Settings and status

- [Settings window](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/SettingsWindowController.swift): `Sources/cbm/UI/SettingsWindowController.swift`
- [Preferences](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Support/Settings.swift): `Sources/cbm/Support/Settings.swift`
- [Live metrics](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/Support/Metrics.swift): `Sources/cbm/Support/Metrics.swift`
- [Login item](https://github.com/henno/macos-clipboard-manager/blob/main/Sources/cbm/UI/LoginItem.swift): `Sources/cbm/UI/LoginItem.swift`

### Other components

- **User**
- **macOS pasteboard**
- **System SQLite**
- **Chrome favicon cache**
- **Previous app**
- **macOS Accessibility**

## Connections

- User → Global hotkey: presses shortcut
- App delegate → Clipboard monitor: starts monitoring
- App delegate → Global hotkey: registers shortcut
- App delegate → Menu bar: installs menu
- Global hotkey → Search panel: opens panel
- Menu bar → Search panel: opens panel
- Menu bar → Settings window: opens settings
- Clipboard monitor → macOS pasteboard: checks changes
- Clipboard monitor → Pasteboard reader: reads changed content
- Pasteboard reader → History store: submits payload
- Clipboard monitor → History store: stores payload
- History store → SQLite database: reads and writes
- History store → Blob and thumbnail files: stores large payloads
- SQLite database → System SQLite: uses
- Search panel → Clipboard monitor: polls before opening
- Search panel → Search index: queries and updates
- Search index → Fuzzy matching: scores terms
- Search index → Text folding: folds query and text
- Search panel → Entry preview: shows selection
- Entry preview → History store: loads full payload
- Search panel → History store: deletes selection
- Search panel → Clipboard restore: restores selection
- Search panel → Frontmost tracker: tracks paste target
- Frontmost tracker → Clipboard restore: provides target app
- Clipboard restore → macOS pasteboard: writes representations
- Clipboard restore → Previous app: activates and pastes
- Settings window → Preferences: reads and updates
- Settings window → History store: applies retention and clears
- Settings window → Live metrics: reads measurements
- Settings window → Login item: configures login
- Clipboard restore → macOS Accessibility: checks permission
- Favicon store → Chrome favicon cache: reads copied cache
- Search panel → Favicon store: warms displayed icons