# elizabeth-ling/otter architecture

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

- Interactive diagram: https://gitdiagram.com/elizabeth-ling/otter
- Repository: https://github.com/elizabeth-ling/otter

## Overview

Otter is a macOS menu-bar note-capture utility, not a notes app. The main workflow is a global hotkey opening a floating editor; submitting creates a durable capture in the outbox, then asynchronous delivery routes it to a configured destination and records recents. The README documents Obsidian and Apple Notes support, though their implementations are not in the supplied tree. Edges reflect sampled source, SOURCE INDEX references, or README statements; unsampled destination links are marked unverified.

Main entry points: [`Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift`](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift) (Delivery service), [`App/Capture/CaptureService.swift`](https://github.com/elizabeth-ling/otter/blob/main/App/Capture/CaptureService.swift) (Capture service), [`App/Panel/PanelController.swift`](https://github.com/elizabeth-ling/otter/blob/main/App/Panel/PanelController.swift) (Panel controller), [`Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift`](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift) (Destination registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Capture interface"]
  node_menu["Menu bar"]
  node_panel_controller["Panel controller"]
  node_panel_view["Capture editor"]
  node_editor["Editor view<br/>[EditorView.swift]"]
  node_panel_geometry["Panel placement"]
end

subgraph group_capture["Capture and delivery"]
  node_drafts[("Draft persistence<br/>[DraftStore.swift]")]
  node_capture_service["Capture service"]
  node_capture_model["Capture model<br/>[Capture.swift]"]
  node_outbox[("Durable outbox<br/>[Outbox.swift]")]
  node_delivery["Delivery service"]
  node_recents[("Recent captures<br/>[RecentStore.swift]")]
end

subgraph group_destinations["Destinations"]
  node_registry["Destination registry"]
  node_destination_protocol["Destination interface<br/>[Destination.swift]"]
  node_folder_destination["Folder destination"]
  node_folder_helpers["Folder file helpers<br/>[FileNamer.swift]"]
  node_folder_bookmark["Folder bookmarks"]
  node_folder_chooser["Folder chooser"]
  node_other_destinations["Obsidian and Notes"]
end

subgraph group_preferences["Hotkeys and state"]
  node_hotkeys["Global hotkeys"]
  node_hotkey_logic["Shortcut logic"]
  node_hotkey_window["Hotkey settings"]
end

node_user(("User"))

node_user -->|"presses shortcut"| node_hotkeys
node_hotkeys -->|"resolves shortcut"| node_hotkey_logic
node_hotkeys -->|"toggles panel"| node_panel_controller
node_menu -->|"opens panel"| node_panel_controller
node_menu -->|"opens chooser"| node_folder_chooser
node_menu -->|"opens settings"| node_hotkey_window
node_panel_controller -->|"builds panel content"| node_panel_view
node_panel_view -->|"renders editor"| node_editor
node_panel_controller -->|"positions panel"| node_panel_geometry
node_panel_controller -->|"restores and saves"| node_drafts
node_panel_view -->|"submits note"| node_capture_service
node_capture_service -->|"creates capture"| node_capture_model
node_capture_service -->|"selects destination"| node_registry
node_capture_service -->|"journals capture"| node_outbox
node_capture_service -->|"starts delivery"| node_delivery
node_delivery -->|"reads pending captures"| node_outbox
node_delivery -->|"looks up destination"| node_registry
node_delivery -->|"records delivery"| node_recents
node_delivery -->|"delivers capture"| node_destination_protocol
node_registry -->|"builds destination"| node_destination_protocol
node_folder_destination -->|"implements"| node_destination_protocol
node_folder_destination -->|"names note files"| node_folder_helpers
node_folder_destination -->|"resolves bookmark"| node_folder_bookmark
node_folder_chooser -->|"updates folder config"| node_registry
node_folder_chooser -->|"retries pending notes"| node_delivery
node_registry -.->|"supports documented backends"| node_other_destinations

click node_hotkeys "https://github.com/elizabeth-ling/otter/blob/main/App/Hotkeys/HotkeyService.swift"
click node_hotkey_logic "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Hotkeys/EffectiveToggleHotkey.swift"
click node_hotkey_window "https://github.com/elizabeth-ling/otter/blob/main/App/Hotkeys/HotkeyWindowController.swift"
click node_menu "https://github.com/elizabeth-ling/otter/blob/main/App/MenuBar/StatusItemController.swift"
click node_panel_controller "https://github.com/elizabeth-ling/otter/blob/main/App/Panel/PanelController.swift"
click node_panel_view "https://github.com/elizabeth-ling/otter/blob/main/App/Panel/PanelContentView.swift"
click node_editor "https://github.com/elizabeth-ling/otter/blob/main/App/Panel/EditorView.swift"
click node_panel_geometry "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Panel/PanelPlacement.swift"
click node_drafts "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/DraftStore.swift"
click node_capture_service "https://github.com/elizabeth-ling/otter/blob/main/App/Capture/CaptureService.swift"
click node_capture_model "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Model/Capture.swift"
click node_outbox "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/Outbox.swift"
click node_delivery "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift"
click node_recents "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/RecentStore.swift"
click node_registry "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift"
click node_destination_protocol "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Destination.swift"
click node_folder_destination "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift"
click node_folder_helpers "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FileNamer.swift"
click node_folder_bookmark "https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderBookmark.swift"
click node_folder_chooser "https://github.com/elizabeth-ling/otter/blob/main/App/MenuBar/FolderChooser.swift"
click node_other_destinations "https://github.com/elizabeth-ling/otter/tree/main/Packages/OtterCore/Sources/OtterCore/Destinations"

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_menu,node_panel_controller,node_panel_view,node_editor,node_panel_geometry,node_user toneBlue
class node_drafts,node_capture_service,node_capture_model,node_outbox,node_delivery,node_recents toneAmber
class node_registry,node_destination_protocol,node_folder_destination,node_folder_helpers,node_folder_bookmark,node_folder_chooser,node_other_destinations toneMint
class node_hotkeys,node_hotkey_logic,node_hotkey_window toneRose
```

## Components

### Capture interface

- [Menu bar](https://github.com/elizabeth-ling/otter/blob/main/App/MenuBar/StatusItemController.swift): `App/MenuBar/StatusItemController.swift`
- [Panel controller](https://github.com/elizabeth-ling/otter/blob/main/App/Panel/PanelController.swift): `App/Panel/PanelController.swift`
- [Capture editor](https://github.com/elizabeth-ling/otter/blob/main/App/Panel/PanelContentView.swift): `App/Panel/PanelContentView.swift`
- [Editor view](https://github.com/elizabeth-ling/otter/blob/main/App/Panel/EditorView.swift): `App/Panel/EditorView.swift`
- [Panel placement](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Panel/PanelPlacement.swift): `Packages/OtterCore/Sources/OtterCore/Panel/PanelPlacement.swift`

### Capture and delivery

- [Draft persistence](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/DraftStore.swift): `Packages/OtterCore/Sources/OtterCore/Pipeline/DraftStore.swift`
- [Capture service](https://github.com/elizabeth-ling/otter/blob/main/App/Capture/CaptureService.swift): `App/Capture/CaptureService.swift`
- [Capture model](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Model/Capture.swift): `Packages/OtterCore/Sources/OtterCore/Model/Capture.swift`
- [Durable outbox](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/Outbox.swift): `Packages/OtterCore/Sources/OtterCore/Pipeline/Outbox.swift`
- [Delivery service](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift): `Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift`
- [Recent captures](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Pipeline/RecentStore.swift): `Packages/OtterCore/Sources/OtterCore/Pipeline/RecentStore.swift`

### Destinations

- [Destination registry](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift): `Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift`
- [Destination interface](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Destination.swift): `Packages/OtterCore/Sources/OtterCore/Destinations/Destination.swift`
- [Folder destination](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift): `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift`
- [Folder file helpers](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FileNamer.swift): `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FileNamer.swift`
- [Folder bookmarks](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderBookmark.swift): `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderBookmark.swift`
- [Folder chooser](https://github.com/elizabeth-ling/otter/blob/main/App/MenuBar/FolderChooser.swift): `App/MenuBar/FolderChooser.swift`
- [Obsidian and Notes](https://github.com/elizabeth-ling/otter/tree/main/Packages/OtterCore/Sources/OtterCore/Destinations): `Packages/OtterCore/Sources/OtterCore/Destinations`

### Hotkeys and state

- [Global hotkeys](https://github.com/elizabeth-ling/otter/blob/main/App/Hotkeys/HotkeyService.swift): `App/Hotkeys/HotkeyService.swift`
- [Shortcut logic](https://github.com/elizabeth-ling/otter/blob/main/Packages/OtterCore/Sources/OtterCore/Hotkeys/EffectiveToggleHotkey.swift): `Packages/OtterCore/Sources/OtterCore/Hotkeys/EffectiveToggleHotkey.swift`
- [Hotkey settings](https://github.com/elizabeth-ling/otter/blob/main/App/Hotkeys/HotkeyWindowController.swift): `App/Hotkeys/HotkeyWindowController.swift`

### Other components

- **User**

## Connections

- User → Global hotkeys: presses shortcut (evidence: `App/Hotkeys/HotkeyService.swift`)
- Global hotkeys → Shortcut logic: resolves shortcut (evidence: `App/Hotkeys/HotkeyService.swift`)
- Global hotkeys → Panel controller: toggles panel (evidence: `App/AppDelegate.swift`)
- Menu bar → Panel controller: opens panel (evidence: `App/MenuBar/StatusItemController.swift`)
- Menu bar → Folder chooser: opens chooser (evidence: `App/MenuBar/StatusItemController.swift`)
- Menu bar → Hotkey settings: opens settings (evidence: `App/MenuBar/StatusItemController.swift`)
- Panel controller → Capture editor: builds panel content (evidence: `App/Panel/PanelController.swift`)
- Capture editor → Editor view: renders editor (evidence: `App/Panel/PanelContentView.swift`)
- Panel controller → Panel placement: positions panel (evidence: `App/Panel/PanelController.swift`)
- Panel controller → Draft persistence: restores and saves (evidence: `App/Panel/PanelController.swift`)
- Capture editor → Capture service: submits note
- Capture service → Capture model: creates capture (evidence: `App/Capture/CaptureService.swift`)
- Capture service → Destination registry: selects destination (evidence: `App/Capture/CaptureService.swift`)
- Capture service → Durable outbox: journals capture (evidence: `App/Capture/CaptureService.swift`)
- Capture service → Delivery service: starts delivery (evidence: `App/Capture/CaptureService.swift`)
- Delivery service → Durable outbox: reads pending captures (evidence: `Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift`)
- Delivery service → Destination registry: looks up destination (evidence: `App/Capture/CapturePipeline.swift`)
- Delivery service → Recent captures: records delivery (evidence: `Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift`)
- Delivery service → Destination interface: delivers capture (evidence: `Packages/OtterCore/Sources/OtterCore/Pipeline/DeliveryService.swift`)
- Destination registry → Destination interface: builds destination (evidence: `Packages/OtterCore/Sources/OtterCore/Destinations/DestinationRegistry.swift`)
- Folder destination → Destination interface: implements (evidence: `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift`)
- Folder destination → Folder file helpers: names note files (evidence: `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift`)
- Folder destination → Folder bookmarks: resolves bookmark (evidence: `Packages/OtterCore/Sources/OtterCore/Destinations/Folder/FolderDestination.swift`)
- Folder chooser → Destination registry: updates folder config (evidence: `App/MenuBar/FolderChooser.swift`)
- Folder chooser → Delivery service: retries pending notes (evidence: `App/MenuBar/FolderChooser.swift`)
- Destination registry → Obsidian and Notes: supports documented backends (evidence: `README.md`)
