# ylam18/flower-hud architecture

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

- Interactive diagram: https://gitdiagram.com/ylam18/flower-hud
- Repository: https://github.com/ylam18/flower-hud

## Overview

Flower is a macOS menu-bar quick-launcher: the user holds a configurable global trigger, chooses an app or command from a radial overlay, and releases to run it. Apps can come from the live Dock or a saved custom preset; app petals can expand into open-window choices, with optional live previews. Settings cover presets, triggers, themes, and permissions. The graph reflects README statements and the supplied source excerpts/index; some internal dispatch details are unsampled, so uncertain links are omitted or marked dashed.

Main entry points: [`Sources/FlowerHUD/Flower/FlowerController.swift`](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerController.swift) (Flower controller), [`Sources/FlowerHUD/Settings/SettingsView.swift`](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/SettingsView.swift) (Settings view), [`Sources/FlowerHUD/AppDelegate.swift`](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/AppDelegate.swift) (App delegate), [`Sources/FlowerHUD/Trigger/TriggerMonitor.swift`](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Trigger/TriggerMonitor.swift) (Trigger monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and triggers"]
  node_appdelegate["App delegate<br/>[AppDelegate.swift]"]
  node_trigger["Trigger monitor"]
  node_triggerconfig["Trigger model<br/>[Trigger.swift]"]
end

subgraph group_overlay["Flower overlay"]
  node_controller["Flower controller"]
  node_view["Flower view<br/>[FlowerView.swift]"]
  node_panel["Flower panel<br/>[FlowerPanel.swift]"]
  node_preview["Window preview panel<br/>[PreviewPanel.swift]"]
  node_theme["Flower themes<br/>[FlowerTheme.swift]"]
end

subgraph group_apps["Apps and actions"]
  node_presetstore[("Preset store<br/>[PresetStore.swift]")]
  node_dockreader["Dock reader<br/>[DockReader.swift]"]
  node_appitem["App item<br/>[AppItem.swift]"]
  node_petalitem["Petal actions<br/>[PetalItem.swift]"]
  node_petallauncher["Petal launcher"]
  node_applauncher["App launcher<br/>[AppLauncher.swift]"]
  node_windowenumerator["Window enumerator"]
  node_windowcapture["Window capture"]
end

subgraph group_configuration["Settings and permissions"]
  node_accessibility["Accessibility access"]
  node_onboarding["Permission onboarding<br/>[Onboarding.swift]"]
  node_screenrecording["Screen Recording access"]
  node_settings["Settings view<br/>[SettingsView.swift]"]
  node_commandeditor["Command editor"]
  node_triggerrecorder["Trigger recorder"]
end

node_user(("User"))
node_macos["macOS services"]

node_user -->|"holds trigger"| node_trigger
node_appdelegate -->|"starts monitor"| node_trigger
node_appdelegate -->|"configures overlay"| node_controller
node_appdelegate -->|"uses settings"| node_presetstore
node_appdelegate -->|"sets up actions"| node_petallauncher
node_trigger -->|"matches binding"| node_triggerconfig
node_trigger -.->|"summons overlay"| node_controller
node_controller -->|"updates display"| node_view
node_controller -->|"shows overlay"| node_panel
node_controller -->|"reads app windows"| node_windowenumerator
node_controller -->|"captures previews"| node_windowcapture
node_controller -->|"shows thumbnail"| node_preview
node_preview -->|"uses colors"| node_theme
node_view -->|"renders with"| node_theme
node_controller -.->|"dispatches selection"| node_petallauncher
node_petallauncher -->|"launches app"| node_applauncher
node_petallauncher -->|"dispatches window actions"| node_windowenumerator
node_windowenumerator -->|"launches if needed"| node_applauncher
node_applauncher -->|"opens application"| node_macos
node_windowcapture -->|"captures screen"| node_macos
node_windowenumerator -->|"uses AX access"| node_accessibility
node_presetstore -->|"reads Dock source"| node_dockreader
node_presetstore -->|"stores custom items"| node_petalitem
node_presetstore -->|"migrates app entries"| node_appitem
node_settings -->|"edits presets"| node_presetstore
node_settings -->|"edits commands"| node_commandeditor
node_settings -->|"records trigger"| node_triggerrecorder
node_settings -->|"offers Dock source"| node_dockreader
node_settings -->|"checks permission"| node_accessibility
node_settings -->|"selects theme"| node_theme
node_appdelegate -->|"starts first-run guide"| node_onboarding
node_onboarding -->|"checks access"| node_accessibility
node_onboarding -->|"checks access"| node_screenrecording
node_trigger -->|"requires permission"| node_accessibility
node_user -->|"configures launcher"| node_settings

click node_appdelegate "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/AppDelegate.swift"
click node_trigger "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Trigger/TriggerMonitor.swift"
click node_triggerconfig "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Trigger/Trigger.swift"
click node_accessibility "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/Accessibility.swift"
click node_onboarding "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/Onboarding.swift"
click node_screenrecording "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/ScreenRecording.swift"
click node_settings "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/SettingsView.swift"
click node_commandeditor "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/CommandEditor.swift"
click node_triggerrecorder "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/TriggerRecorder.swift"
click node_presetstore "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PresetStore.swift"
click node_dockreader "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/DockReader.swift"
click node_appitem "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/AppItem.swift"
click node_petalitem "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PetalItem.swift"
click node_petallauncher "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PetalLauncher.swift"
click node_applauncher "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/AppLauncher.swift"
click node_windowenumerator "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/WindowEnumerator.swift"
click node_windowcapture "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/WindowCapture.swift"
click node_controller "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerController.swift"
click node_view "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerView.swift"
click node_panel "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerPanel.swift"
click node_preview "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/PreviewPanel.swift"
click node_theme "https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerTheme.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_appdelegate,node_trigger,node_triggerconfig,node_user toneBlue
class node_controller,node_view,node_panel,node_preview,node_theme toneAmber
class node_presetstore,node_dockreader,node_appitem,node_petalitem,node_petallauncher,node_applauncher,node_windowenumerator,node_windowcapture toneMint
class node_accessibility,node_onboarding,node_screenrecording,node_settings,node_commandeditor,node_triggerrecorder toneRose
class node_macos toneIndigo
```

## Components

### Runtime and triggers

- [App delegate](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/AppDelegate.swift): `Sources/FlowerHUD/AppDelegate.swift`
- [Trigger monitor](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Trigger/TriggerMonitor.swift): `Sources/FlowerHUD/Trigger/TriggerMonitor.swift`
- [Trigger model](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Trigger/Trigger.swift): `Sources/FlowerHUD/Trigger/Trigger.swift`

### Flower overlay

- [Flower controller](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerController.swift): `Sources/FlowerHUD/Flower/FlowerController.swift`
- [Flower view](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerView.swift): `Sources/FlowerHUD/Flower/FlowerView.swift`
- [Flower panel](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerPanel.swift): `Sources/FlowerHUD/Flower/FlowerPanel.swift`
- [Window preview panel](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/PreviewPanel.swift): `Sources/FlowerHUD/Flower/PreviewPanel.swift`
- [Flower themes](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Flower/FlowerTheme.swift): `Sources/FlowerHUD/Flower/FlowerTheme.swift`

### Apps and actions

- [Preset store](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PresetStore.swift): `Sources/FlowerHUD/Apps/PresetStore.swift`
- [Dock reader](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/DockReader.swift): `Sources/FlowerHUD/Apps/DockReader.swift`
- [App item](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/AppItem.swift): `Sources/FlowerHUD/Apps/AppItem.swift`
- [Petal actions](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PetalItem.swift): `Sources/FlowerHUD/Apps/PetalItem.swift`
- [Petal launcher](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/PetalLauncher.swift): `Sources/FlowerHUD/Apps/PetalLauncher.swift`
- [App launcher](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/AppLauncher.swift): `Sources/FlowerHUD/Apps/AppLauncher.swift`
- [Window enumerator](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/WindowEnumerator.swift): `Sources/FlowerHUD/Apps/WindowEnumerator.swift`
- [Window capture](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Apps/WindowCapture.swift): `Sources/FlowerHUD/Apps/WindowCapture.swift`

### Settings and permissions

- [Accessibility access](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/Accessibility.swift): `Sources/FlowerHUD/Permissions/Accessibility.swift`
- [Permission onboarding](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/Onboarding.swift): `Sources/FlowerHUD/Permissions/Onboarding.swift`
- [Screen Recording access](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Permissions/ScreenRecording.swift): `Sources/FlowerHUD/Permissions/ScreenRecording.swift`
- [Settings view](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/SettingsView.swift): `Sources/FlowerHUD/Settings/SettingsView.swift`
- [Command editor](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/CommandEditor.swift): `Sources/FlowerHUD/Settings/CommandEditor.swift`
- [Trigger recorder](https://github.com/ylam18/flower-hud/blob/main/Sources/FlowerHUD/Settings/TriggerRecorder.swift): `Sources/FlowerHUD/Settings/TriggerRecorder.swift`

### Other components

- **User**
- **macOS services**

## Connections

- User → Trigger monitor: holds trigger (evidence: `README.md`)
- App delegate → Trigger monitor: starts monitor (evidence: `Sources/FlowerHUD/AppDelegate.swift`)
- App delegate → Flower controller: configures overlay (evidence: `Sources/FlowerHUD/AppDelegate.swift`)
- App delegate → Preset store: uses settings (evidence: `Sources/FlowerHUD/AppDelegate.swift`)
- App delegate → Petal launcher: sets up actions (evidence: `Sources/FlowerHUD/AppDelegate.swift`)
- Trigger monitor → Trigger model: matches binding (evidence: `Sources/FlowerHUD/Trigger/TriggerMonitor.swift`)
- Trigger monitor → Flower controller: summons overlay
- Flower controller → Flower view: updates display (evidence: `Sources/FlowerHUD/Flower/FlowerController.swift`)
- Flower controller → Flower panel: shows overlay (evidence: `Sources/FlowerHUD/Flower/FlowerController.swift`)
- Flower controller → Window enumerator: reads app windows (evidence: `Sources/FlowerHUD/Flower/FlowerController.swift`)
- Flower controller → Window capture: captures previews (evidence: `Sources/FlowerHUD/Flower/FlowerController.swift`)
- Flower controller → Window preview panel: shows thumbnail (evidence: `Sources/FlowerHUD/Flower/FlowerController.swift`)
- Window preview panel → Flower themes: uses colors (evidence: `Sources/FlowerHUD/Flower/PreviewPanel.swift`)
- Flower view → Flower themes: renders with (evidence: `Sources/FlowerHUD/Flower/FlowerView.swift`)
- Flower controller → Petal launcher: dispatches selection
- Petal launcher → App launcher: launches app (evidence: `Sources/FlowerHUD/Apps/PetalLauncher.swift`)
- Petal launcher → Window enumerator: dispatches window actions (evidence: `Sources/FlowerHUD/Apps/PetalLauncher.swift`)
- Window enumerator → App launcher: launches if needed (evidence: `Sources/FlowerHUD/Apps/WindowEnumerator.swift`)
- App launcher → macOS services: opens application (evidence: `README.md`)
- Window capture → macOS services: captures screen (evidence: `README.md`)
- Window enumerator → Accessibility access: uses AX access (evidence: `Sources/FlowerHUD/Apps/WindowEnumerator.swift`)
- Preset store → Dock reader: reads Dock source (evidence: `Sources/FlowerHUD/Apps/PresetStore.swift`)
- Preset store → Petal actions: stores custom items (evidence: `Sources/FlowerHUD/Apps/PresetStore.swift`)
- Preset store → App item: migrates app entries (evidence: `Sources/FlowerHUD/Apps/PresetStore.swift`)
- Settings view → Preset store: edits presets (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- Settings view → Command editor: edits commands (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- Settings view → Trigger recorder: records trigger (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- Settings view → Dock reader: offers Dock source (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- Settings view → Accessibility access: checks permission (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- Settings view → Flower themes: selects theme (evidence: `Sources/FlowerHUD/Settings/SettingsView.swift`)
- App delegate → Permission onboarding: starts first-run guide (evidence: `Sources/FlowerHUD/AppDelegate.swift`)
- Permission onboarding → Accessibility access: checks access (evidence: `Sources/FlowerHUD/Permissions/Onboarding.swift`)
- Permission onboarding → Screen Recording access: checks access (evidence: `Sources/FlowerHUD/Permissions/Onboarding.swift`)
- Trigger monitor → Accessibility access: requires permission (evidence: `README.md`)
- User → Settings view: configures launcher (evidence: `README.md`)
