# 1of1adam/droppy architecture

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

- Interactive diagram: https://gitdiagram.com/1of1adam/droppy
- Repository: https://github.com/1of1adam/droppy

## Overview

Droppy is a native macOS productivity app centered on a notch-style shelf, with floating baskets, clipboard history, HUDs, and installable extensions. The primary workflow is to drop or capture items, manage them in the shelf or a basket, then use actions such as sharing, conversion, or OCR. The graph combines documented capabilities with relationships visible in the supplied source index and excerpts; unsampled implementation details are represented only at supported directory level.

Main entry points: [`Droppy/NotchWindowController.swift`](https://github.com/1of1adam/droppy/blob/main/Droppy/NotchWindowController.swift) (Notch controller), [`Droppy/FloatingBasketWindowController.swift`](https://github.com/1of1adam/droppy/blob/main/Droppy/FloatingBasketWindowController.swift) (Floating baskets), [`Droppy/ClipboardManagerView.swift`](https://github.com/1of1adam/droppy/blob/main/Droppy/ClipboardManagerView.swift) (Clipboard viewer), [`Droppy/MusicManager.swift`](https://github.com/1of1adam/droppy/blob/main/Droppy/MusicManager.swift) (Now playing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Shelf and baskets"]
  node_notch["Notch controller"]
  node_shelf["File shelf"]
  node_appstate["Shelf state<br/>[DroppyState.swift]"]
  node_drag["Drag monitor<br/>[DragMonitor.swift]"]
  node_basket["Floating baskets"]
  node_basketstate["Basket state<br/>[BasketState.swift]"]
end

subgraph group_content["Content tools"]
  node_item["File items<br/>[DroppedItem.swift]"]
  node_clipboard["Clipboard history"]
  node_clipboardui["Clipboard viewer"]
  node_quickshare["Quickshare"]
  node_filetools["File conversion"]
  node_ocr["OCR service<br/>[OCRService.swift]"]
end

subgraph group_system["System overlays"]
  node_hud["HUD manager<br/>[HUDManager.swift]"]
  node_music["Now playing<br/>[MusicManager.swift]"]
  node_spotify["Spotify controls"]
  node_applemusic["Apple Music controls"]
end

subgraph group_extensions["Extensions"]
  node_extensions["Productivity extensions"]
  node_todo["Reminders and tasks<br/>[ToDoManager.swift]"]
  node_capture["Element capture"]
end

subgraph group_foundation["Shared foundations"]
  node_hotkey["Global shortcuts<br/>[GlobalHotKey.swift]"]
  node_permissions["Permission manager"]
  node_tempfiles["Temporary files"]
  node_analytics["Analytics service"]
end

node_user(("Mac user"))

node_user -->|"opens notch"| node_notch
node_notch -->|"shows shelf"| node_shelf
node_notch -->|"reads state"| node_appstate
node_user -->|"drops files"| node_shelf
node_shelf -.->|"manages items"| node_appstate
node_appstate -->|"stores items"| node_item
node_user -->|"drags items"| node_drag
node_drag -->|"spawns basket"| node_basket
node_basket -->|"manages contents"| node_basketstate
node_basket -->|"displays items"| node_item
node_item -->|"creates temporary files"| node_tempfiles
node_user -->|"searches history"| node_clipboardui
node_clipboardui -->|"uses history"| node_clipboard
node_clipboard -->|"checks access"| node_permissions
node_clipboardui -->|"requests OCR"| node_ocr
node_user -->|"shares files"| node_quickshare
node_user -->|"converts files"| node_filetools
node_notch -->|"shows overlays"| node_hud
node_notch -->|"reads playback"| node_music
node_music -->|"controls playback"| node_spotify
node_music -->|"controls playback"| node_applemusic
node_user -->|"installs extensions"| node_extensions
node_user -->|"captures tasks"| node_todo
node_user -->|"captures elements"| node_capture
node_capture -->|"registers shortcuts"| node_hotkey
node_hotkey -->|"checks access"| node_permissions
node_extensions -.->|"tracks activation"| node_analytics

click node_notch "https://github.com/1of1adam/droppy/blob/main/Droppy/NotchWindowController.swift"
click node_shelf "https://github.com/1of1adam/droppy/blob/main/Droppy/NotchShelfView.swift"
click node_appstate "https://github.com/1of1adam/droppy/blob/main/Droppy/DroppyState.swift"
click node_drag "https://github.com/1of1adam/droppy/blob/main/Droppy/DragMonitor.swift"
click node_basket "https://github.com/1of1adam/droppy/blob/main/Droppy/FloatingBasketWindowController.swift"
click node_basketstate "https://github.com/1of1adam/droppy/blob/main/Droppy/BasketState.swift"
click node_item "https://github.com/1of1adam/droppy/blob/main/Droppy/DroppedItem.swift"
click node_clipboard "https://github.com/1of1adam/droppy/blob/main/Droppy/ClipboardManager.swift"
click node_clipboardui "https://github.com/1of1adam/droppy/blob/main/Droppy/ClipboardManagerView.swift"
click node_quickshare "https://github.com/1of1adam/droppy/blob/main/Droppy/QuickshareManager.swift"
click node_filetools "https://github.com/1of1adam/droppy/blob/main/Droppy/FileConverter.swift"
click node_ocr "https://github.com/1of1adam/droppy/blob/main/Droppy/OCRService.swift"
click node_hud "https://github.com/1of1adam/droppy/blob/main/Droppy/HUDManager.swift"
click node_music "https://github.com/1of1adam/droppy/blob/main/Droppy/MusicManager.swift"
click node_extensions "https://github.com/1of1adam/droppy/tree/main/Droppy/Extensions"
click node_todo "https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/ToDo/ToDoManager.swift"
click node_capture "https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/ElementCapture/ElementCaptureManager.swift"
click node_hotkey "https://github.com/1of1adam/droppy/blob/main/Droppy/GlobalHotKey.swift"
click node_permissions "https://github.com/1of1adam/droppy/blob/main/Droppy/PermissionManager.swift"
click node_tempfiles "https://github.com/1of1adam/droppy/blob/main/Droppy/TemporaryFileStorageService.swift"
click node_analytics "https://github.com/1of1adam/droppy/blob/main/Droppy/AnalyticsService.swift"
click node_spotify "https://github.com/1of1adam/droppy/blob/main/Droppy/SpotifyController.swift"
click node_applemusic "https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/AppleMusic/AppleMusicController.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_notch,node_shelf,node_appstate,node_drag,node_basket,node_basketstate,node_user toneBlue
class node_item,node_clipboard,node_clipboardui,node_quickshare,node_filetools,node_ocr toneAmber
class node_hud,node_music,node_spotify,node_applemusic toneMint
class node_extensions,node_todo,node_capture toneRose
class node_hotkey,node_permissions,node_tempfiles,node_analytics toneIndigo
```

## Components

### Shelf and baskets

- [Notch controller](https://github.com/1of1adam/droppy/blob/main/Droppy/NotchWindowController.swift): `Droppy/NotchWindowController.swift`
- [File shelf](https://github.com/1of1adam/droppy/blob/main/Droppy/NotchShelfView.swift): `Droppy/NotchShelfView.swift`
- [Shelf state](https://github.com/1of1adam/droppy/blob/main/Droppy/DroppyState.swift): `Droppy/DroppyState.swift`
- [Drag monitor](https://github.com/1of1adam/droppy/blob/main/Droppy/DragMonitor.swift): `Droppy/DragMonitor.swift`
- [Floating baskets](https://github.com/1of1adam/droppy/blob/main/Droppy/FloatingBasketWindowController.swift): `Droppy/FloatingBasketWindowController.swift`
- [Basket state](https://github.com/1of1adam/droppy/blob/main/Droppy/BasketState.swift): `Droppy/BasketState.swift`

### Content tools

- [File items](https://github.com/1of1adam/droppy/blob/main/Droppy/DroppedItem.swift): `Droppy/DroppedItem.swift`
- [Clipboard history](https://github.com/1of1adam/droppy/blob/main/Droppy/ClipboardManager.swift): `Droppy/ClipboardManager.swift`
- [Clipboard viewer](https://github.com/1of1adam/droppy/blob/main/Droppy/ClipboardManagerView.swift): `Droppy/ClipboardManagerView.swift`
- [Quickshare](https://github.com/1of1adam/droppy/blob/main/Droppy/QuickshareManager.swift): `Droppy/QuickshareManager.swift`
- [File conversion](https://github.com/1of1adam/droppy/blob/main/Droppy/FileConverter.swift): `Droppy/FileConverter.swift`
- [OCR service](https://github.com/1of1adam/droppy/blob/main/Droppy/OCRService.swift): `Droppy/OCRService.swift`

### System overlays

- [HUD manager](https://github.com/1of1adam/droppy/blob/main/Droppy/HUDManager.swift): `Droppy/HUDManager.swift`
- [Now playing](https://github.com/1of1adam/droppy/blob/main/Droppy/MusicManager.swift): `Droppy/MusicManager.swift`
- [Spotify controls](https://github.com/1of1adam/droppy/blob/main/Droppy/SpotifyController.swift): `Droppy/SpotifyController.swift`
- [Apple Music controls](https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/AppleMusic/AppleMusicController.swift): `Droppy/Extensions/AppleMusic/AppleMusicController.swift`

### Extensions

- [Productivity extensions](https://github.com/1of1adam/droppy/tree/main/Droppy/Extensions): `Droppy/Extensions`
- [Reminders and tasks](https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/ToDo/ToDoManager.swift): `Droppy/Extensions/ToDo/ToDoManager.swift`
- [Element capture](https://github.com/1of1adam/droppy/blob/main/Droppy/Extensions/ElementCapture/ElementCaptureManager.swift): `Droppy/Extensions/ElementCapture/ElementCaptureManager.swift`

### Shared foundations

- [Global shortcuts](https://github.com/1of1adam/droppy/blob/main/Droppy/GlobalHotKey.swift): `Droppy/GlobalHotKey.swift`
- [Permission manager](https://github.com/1of1adam/droppy/blob/main/Droppy/PermissionManager.swift): `Droppy/PermissionManager.swift`
- [Temporary files](https://github.com/1of1adam/droppy/blob/main/Droppy/TemporaryFileStorageService.swift): `Droppy/TemporaryFileStorageService.swift`
- [Analytics service](https://github.com/1of1adam/droppy/blob/main/Droppy/AnalyticsService.swift): `Droppy/AnalyticsService.swift`

### Other components

- **Mac user**

## Connections

- Mac user → Notch controller: opens notch (evidence: `README.md`)
- Notch controller → File shelf: shows shelf (evidence: `Droppy/NotchWindowController.swift`)
- Notch controller → Shelf state: reads state (evidence: `Droppy/NotchWindowController.swift`)
- Mac user → File shelf: drops files (evidence: `README.md`)
- File shelf → Shelf state: manages items
- Shelf state → File items: stores items (evidence: `Droppy/DroppyState.swift`)
- Mac user → Drag monitor: drags items (evidence: `README.md`)
- Drag monitor → Floating baskets: spawns basket (evidence: `Droppy/DragMonitor.swift`)
- Floating baskets → Basket state: manages contents (evidence: `Droppy/FloatingBasketWindowController.swift`)
- Floating baskets → File items: displays items (evidence: `Droppy/FloatingBasketWindowController.swift`)
- File items → Temporary files: creates temporary files (evidence: `Droppy/DroppedItem.swift`)
- Mac user → Clipboard viewer: searches history (evidence: `README.md`)
- Clipboard viewer → Clipboard history: uses history (evidence: `Droppy/ClipboardManagerView.swift`)
- Clipboard history → Permission manager: checks access (evidence: `Droppy/ClipboardManager.swift`)
- Clipboard viewer → OCR service: requests OCR (evidence: `Droppy/ClipboardManagerView.swift`)
- Mac user → Quickshare: shares files (evidence: `README.md`)
- Mac user → File conversion: converts files (evidence: `README.md`)
- Notch controller → HUD manager: shows overlays (evidence: `Droppy/NotchWindowController.swift`)
- Notch controller → Now playing: reads playback (evidence: `Droppy/NotchWindowController.swift`)
- Now playing → Spotify controls: controls playback (evidence: `Droppy/MusicManager.swift`)
- Now playing → Apple Music controls: controls playback (evidence: `Droppy/MusicManager.swift`)
- Mac user → Productivity extensions: installs extensions (evidence: `README.md`)
- Mac user → Reminders and tasks: captures tasks (evidence: `README.md`)
- Mac user → Element capture: captures elements (evidence: `README.md`)
- Element capture → Global shortcuts: registers shortcuts (evidence: `Droppy/Extensions/ElementCapture/ElementCaptureManager.swift`)
- Global shortcuts → Permission manager: checks access (evidence: `Droppy/GlobalHotKey.swift`)
- Productivity extensions → Analytics service: tracks activation (evidence: `Droppy/Extensions/AIBackgroundRemoval/AIInstallManager.swift`)
