# brightwav3/winv architecture

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

- Interactive diagram: https://gitdiagram.com/brightwav3/winv
- Repository: https://github.com/brightwav3/winv

## Overview

WinV is a macOS clipboard-history app. Its main workflow is: a global shortcut opens the history panel, the user selects a saved clip, and WinV restores it to the clipboard and pastes into the previous app. Separately, a background watcher captures clipboard changes into persistent history. Settings configure shortcuts, appearance, and recording; the app also checks and installs signed updates. The graph reflects documented behavior and shown calls; some UI-to-rendering and paste wiring is documented but not visible in the sampled excerpts.

Main entry points: [`Sources/WinV/App.swift`](https://github.com/brightwav3/winv/blob/main/Sources/WinV/App.swift) (App lifecycle and menu), [`Sources/WinV/Store.swift`](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Store.swift) (History and settings), [`Sources/WinV/Panel.swift`](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Panel.swift) (History panel), [`Sources/WinV/Windows.swift`](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Windows.swift) (Settings and onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and interaction"]
  node_app["App lifecycle and menu<br/>[App.swift]"]
  node_hotkeys["Global shortcuts<br/>[System.swift]"]
  node_panel["History panel<br/>[Panel.swift]"]
  node_paste["Paste dispatch<br/>[System.swift]"]
end

subgraph group_history["Capture and history"]
  node_watcher["Clipboard capture<br/>[Store.swift]"]
  node_store["History and settings<br/>[Store.swift]"]
  node_disk[("History files")]
end

subgraph group_presentation["UI and appearance"]
  node_settings["Settings and onboarding<br/>[Windows.swift]"]
  node_glass["Glass surfaces<br/>[Glass.swift]"]
  node_theme["Theme and styles<br/>[Theme.swift]"]
end

subgraph group_updates["Updates"]
  node_updater["Update checker and installer<br/>[Updater.swift]"]
end

node_user(("User"))
node_macos["macOS services"]
node_target["Frontmost app"]
node_github["GitHub Releases"]

node_user -->|"presses shortcut"| node_hotkeys
node_hotkeys -->|"opens panel"| node_panel
node_user -->|"selects clip"| node_panel
node_panel -->|"uses history"| node_store
node_panel -.->|"requests paste"| node_paste
node_paste -->|"restores clip"| node_store
node_paste -->|"sends paste"| node_target
node_watcher -->|"reads clipboard"| node_macos
node_watcher -->|"records clips"| node_store
node_store -->|"persists history"| node_disk
node_store -->|"writes clipboard"| node_macos
node_app -->|"starts watcher"| node_watcher
node_app -->|"registers shortcut"| node_hotkeys
node_app -->|"syncs pins"| node_store
node_app -->|"opens onboarding"| node_settings
node_app -->|"applies appearance"| node_theme
node_user -->|"changes preferences"| node_settings
node_settings -->|"sets shortcuts"| node_hotkeys
node_panel -->|"uses glass UI"| node_glass
node_settings -->|"tunes glass"| node_glass
node_app -->|"starts updates"| node_updater
node_updater -->|"checks releases"| node_github
node_updater -->|"notifies and installs"| node_macos

click node_app "https://github.com/brightwav3/winv/blob/main/Sources/WinV/App.swift"
click node_hotkeys "https://github.com/brightwav3/winv/blob/main/Sources/WinV/System.swift"
click node_panel "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Panel.swift"
click node_paste "https://github.com/brightwav3/winv/blob/main/Sources/WinV/System.swift"
click node_watcher "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Store.swift"
click node_store "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Store.swift"
click node_settings "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Windows.swift"
click node_glass "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Glass.swift"
click node_theme "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Theme.swift"
click node_updater "https://github.com/brightwav3/winv/blob/main/Sources/WinV/Updater.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_hotkeys,node_panel,node_paste,node_user toneBlue
class node_watcher,node_store,node_disk toneAmber
class node_settings,node_glass,node_theme toneMint
class node_updater toneRose
class node_macos,node_target,node_github toneIndigo
```

## Components

### App and interaction

- [App lifecycle and menu](https://github.com/brightwav3/winv/blob/main/Sources/WinV/App.swift): `Sources/WinV/App.swift`
- [Global shortcuts](https://github.com/brightwav3/winv/blob/main/Sources/WinV/System.swift): `Sources/WinV/System.swift`
- [History panel](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Panel.swift): `Sources/WinV/Panel.swift`
- [Paste dispatch](https://github.com/brightwav3/winv/blob/main/Sources/WinV/System.swift): `Sources/WinV/System.swift`

### Capture and history

- [Clipboard capture](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Store.swift): `Sources/WinV/Store.swift`
- [History and settings](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Store.swift): `Sources/WinV/Store.swift`
- **History files**

### UI and appearance

- [Settings and onboarding](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Windows.swift): `Sources/WinV/Windows.swift`
- [Glass surfaces](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Glass.swift): `Sources/WinV/Glass.swift`
- [Theme and styles](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Theme.swift): `Sources/WinV/Theme.swift`

### Updates

- [Update checker and installer](https://github.com/brightwav3/winv/blob/main/Sources/WinV/Updater.swift): `Sources/WinV/Updater.swift`

### Other components

- **User**
- **macOS services**
- **Frontmost app**
- **GitHub Releases**

## Connections

- User → Global shortcuts: presses shortcut (evidence: `README.md`)
- Global shortcuts → History panel: opens panel (evidence: `Sources/WinV/System.swift`)
- User → History panel: selects clip (evidence: `README.md`)
- History panel → History and settings: uses history (evidence: `Sources/WinV/Panel.swift`)
- History panel → Paste dispatch: requests paste
- Paste dispatch → History and settings: restores clip (evidence: `Sources/WinV/Store.swift`)
- Paste dispatch → Frontmost app: sends paste (evidence: `Sources/WinV/System.swift`)
- Clipboard capture → macOS services: reads clipboard (evidence: `README.md`)
- Clipboard capture → History and settings: records clips (evidence: `Sources/WinV/Store.swift`)
- History and settings → History files: persists history (evidence: `README.md`)
- History and settings → macOS services: writes clipboard (evidence: `Sources/WinV/Store.swift`)
- App lifecycle and menu → Clipboard capture: starts watcher (evidence: `Sources/WinV/App.swift`)
- App lifecycle and menu → Global shortcuts: registers shortcut (evidence: `Sources/WinV/App.swift`)
- App lifecycle and menu → History and settings: syncs pins (evidence: `Sources/WinV/App.swift`)
- App lifecycle and menu → Settings and onboarding: opens onboarding (evidence: `Sources/WinV/App.swift`)
- App lifecycle and menu → Theme and styles: applies appearance (evidence: `Sources/WinV/App.swift`)
- User → Settings and onboarding: changes preferences (evidence: `README.md`)
- Settings and onboarding → Global shortcuts: sets shortcuts (evidence: `Sources/WinV/Windows.swift`)
- History panel → Glass surfaces: uses glass UI (evidence: `README.md`)
- Settings and onboarding → Glass surfaces: tunes glass (evidence: `README.md`)
- App lifecycle and menu → Update checker and installer: starts updates (evidence: `Sources/WinV/App.swift`)
- Update checker and installer → GitHub Releases: checks releases (evidence: `Sources/WinV/Updater.swift`)
- Update checker and installer → macOS services: notifies and installs (evidence: `Sources/WinV/Updater.swift`)
