# is52hertz/relay architecture

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

- Interactive diagram: https://gitdiagram.com/is52hertz/relay
- Repository: https://github.com/is52hertz/relay

## Overview

Relay is a native macOS menu-bar app switcher: users create Profiles, bind global hotkeys to target apps, choose reusable state-based activation behaviors, then trigger those bindings from anywhere. The active Profile’s bindings are registered and dispatched to the activation engine, which inspects app state and performs the configured action. Separate branches cover settings, local configuration and backup management. The graph uses the README and source index references; unsampled implementations are represented only where documented or referenced, so some internal wiring is omitted.

Main entry points: [`Relay/Relay/State/AppModel.swift`](https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppModel.swift) (App Model), [`Relay/Relay/Services/AppActivationService.swift`](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/AppActivationService.swift) (Activation Service), [`Relay/Relay/State/AppController.swift`](https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppController.swift) (App Controller), [`Relay/Relay/RelayApp.swift`](https://github.com/is52hertz/relay/blob/main/Relay/Relay/RelayApp.swift) (Relay App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_relayapp["Relay App<br/>[RelayApp.swift]"]
  node_controller["App Controller"]
  node_menubar["Menu Bar"]
end

subgraph group_profiles["Profiles and Hotkeys"]
  node_profilesui["Profiles UI<br/>[ProfilesView.swift]"]
  node_bindingsui["Binding Editor"]
  node_recorder["Shortcut Recorder"]
  node_registration["Hotkey Registration"]
end

subgraph group_activation["Activation Engine"]
  node_activation["Activation Service"]
  node_decision["Activation Decisions"]
  node_resolver["Target App Resolver"]
  node_frontmost["Frontmost Tracker"]
  node_minimizer["Window Minimizer"]
end

subgraph group_data["Configuration and Data"]
  node_model["App Model<br/>[AppModel.swift]"]
  node_configuration["Configuration Models"]
  node_persistence[("Local Persistence")]
  node_dataui["Data Settings"]
  node_backup["Backup Service"]
end

subgraph group_settings["Settings and Services"]
  node_settingsui["Settings UI"]
  node_personalization["Personalization UI"]
  node_language["Language Service"]
  node_login["Login Item Service"]
  node_dock["Dock Icon Controller"]
end

node_user(("User"))
node_hotkeylib["KeyboardShortcuts"]
node_workspace["macOS AppKit"]

node_user -->|"opens"| node_relayapp
node_relayapp -->|"creates"| node_controller
node_relayapp -->|"presents"| node_menubar
node_relayapp -->|"presents"| node_profilesui
node_user -->|"manages profiles"| node_profilesui
node_profilesui -->|"shows details"| node_bindingsui
node_bindingsui -->|"edits bindings"| node_model
node_bindingsui -->|"uses recorder"| node_recorder
node_model -->|"loads and saves"| node_persistence
node_model -->|"holds"| node_configuration
node_controller -->|"creates"| node_model
node_controller -->|"configures"| node_registration
node_model -->|"signals profile changes"| node_registration
node_registration -->|"registers shortcuts"| node_hotkeylib
node_registration -->|"dispatches bindings"| node_activation
node_activation -->|"selects action"| node_decision
node_activation -->|"checks app state"| node_resolver
node_activation -->|"checks foreground"| node_frontmost
node_activation -->|"controls windows"| node_minimizer
node_activation -->|"launches and focuses"| node_workspace
node_minimizer -.->|"uses Accessibility"| node_workspace
node_user -->|"manages backups"| node_dataui
node_dataui -->|"reads configuration"| node_model
node_dataui -->|"imports and exports"| node_backup
node_backup -->|"uses data directory"| node_persistence
node_user -->|"changes settings"| node_settingsui
node_settingsui -.->|"updates preferences"| node_model
node_personalization -->|"updates language choice"| node_model
node_personalization -->|"requests language change"| node_language
node_controller -->|"applies login setting"| node_login
node_controller -->|"applies Dock setting"| node_dock

click node_relayapp "https://github.com/is52hertz/relay/blob/main/Relay/Relay/RelayApp.swift"
click node_controller "https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppController.swift"
click node_menubar "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/MenuBarContent.swift"
click node_profilesui "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/ProfilesView.swift"
click node_bindingsui "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/BindingsDetailView.swift"
click node_recorder "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/ShortcutRecorder.swift"
click node_model "https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppModel.swift"
click node_configuration "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Models/AppConfiguration.swift"
click node_persistence "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Persistence/PersistenceStore.swift"
click node_dataui "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/DataSettingsView.swift"
click node_backup "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/BackupService.swift"
click node_registration "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/HotkeyRegistrationService.swift"
click node_activation "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/AppActivationService.swift"
click node_decision "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/AppActivationDecision.swift"
click node_resolver "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/TargetAppResolver.swift"
click node_frontmost "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/FrontmostTracker.swift"
click node_minimizer "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/WindowMinimizer.swift"
click node_settingsui "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/GeneralSettingsView.swift"
click node_personalization "https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/PersonalizationSettingsView.swift"
click node_language "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/LanguageService.swift"
click node_login "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/LoginItemService.swift"
click node_dock "https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/DockIconController.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_relayapp,node_controller,node_menubar,node_user toneBlue
class node_profilesui,node_bindingsui,node_recorder,node_registration toneAmber
class node_activation,node_decision,node_resolver,node_frontmost,node_minimizer toneMint
class node_model,node_configuration,node_persistence,node_dataui,node_backup toneRose
class node_settingsui,node_personalization,node_language,node_login,node_dock,node_hotkeylib,node_workspace toneIndigo
```

## Components

### App Shell

- [Relay App](https://github.com/is52hertz/relay/blob/main/Relay/Relay/RelayApp.swift): `Relay/Relay/RelayApp.swift`
- [App Controller](https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppController.swift): `Relay/Relay/State/AppController.swift`
- [Menu Bar](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/MenuBarContent.swift): `Relay/Relay/UI/MenuBarContent.swift`

### Profiles and Hotkeys

- [Profiles UI](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/ProfilesView.swift): `Relay/Relay/UI/ProfilesView.swift`
- [Binding Editor](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/BindingsDetailView.swift): `Relay/Relay/UI/BindingsDetailView.swift`
- [Shortcut Recorder](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/ShortcutRecorder.swift): `Relay/Relay/UI/ShortcutRecorder.swift`
- [Hotkey Registration](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/HotkeyRegistrationService.swift): `Relay/Relay/Services/HotkeyRegistrationService.swift`

### Activation Engine

- [Activation Service](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/AppActivationService.swift): `Relay/Relay/Services/AppActivationService.swift`
- [Activation Decisions](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/AppActivationDecision.swift): `Relay/Relay/Services/AppActivationDecision.swift`
- [Target App Resolver](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/TargetAppResolver.swift): `Relay/Relay/Services/TargetAppResolver.swift`
- [Frontmost Tracker](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/FrontmostTracker.swift): `Relay/Relay/Services/FrontmostTracker.swift`
- [Window Minimizer](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/WindowMinimizer.swift): `Relay/Relay/Services/WindowMinimizer.swift`

### Configuration and Data

- [App Model](https://github.com/is52hertz/relay/blob/main/Relay/Relay/State/AppModel.swift): `Relay/Relay/State/AppModel.swift`
- [Configuration Models](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Models/AppConfiguration.swift): `Relay/Relay/Models/AppConfiguration.swift`
- [Local Persistence](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Persistence/PersistenceStore.swift): `Relay/Relay/Persistence/PersistenceStore.swift`
- [Data Settings](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/DataSettingsView.swift): `Relay/Relay/UI/DataSettingsView.swift`
- [Backup Service](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/BackupService.swift): `Relay/Relay/Services/BackupService.swift`

### Settings and Services

- [Settings UI](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/GeneralSettingsView.swift): `Relay/Relay/UI/GeneralSettingsView.swift`
- [Personalization UI](https://github.com/is52hertz/relay/blob/main/Relay/Relay/UI/PersonalizationSettingsView.swift): `Relay/Relay/UI/PersonalizationSettingsView.swift`
- [Language Service](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/LanguageService.swift): `Relay/Relay/Services/LanguageService.swift`
- [Login Item Service](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/LoginItemService.swift): `Relay/Relay/Services/LoginItemService.swift`
- [Dock Icon Controller](https://github.com/is52hertz/relay/blob/main/Relay/Relay/Services/DockIconController.swift): `Relay/Relay/Services/DockIconController.swift`

### Other components

- **User**
- **KeyboardShortcuts**
- **macOS AppKit**

## Connections

- User → Relay App: opens (evidence: `README.md`)
- Relay App → App Controller: creates (evidence: `Relay/Relay/RelayApp.swift`)
- Relay App → Menu Bar: presents (evidence: `Relay/Relay/RelayApp.swift`)
- Relay App → Profiles UI: presents (evidence: `Relay/Relay/RelayApp.swift`)
- User → Profiles UI: manages profiles (evidence: `README.md`)
- Profiles UI → Binding Editor: shows details (evidence: `Relay/Relay/UI/ProfilesView.swift`)
- Binding Editor → App Model: edits bindings (evidence: `Relay/Relay/UI/BindingsDetailView.swift`)
- Binding Editor → Shortcut Recorder: uses recorder (evidence: `Relay/Relay/UI/BindingsDetailView.swift`)
- App Model → Local Persistence: loads and saves (evidence: `Relay/Relay/State/AppModel.swift`)
- App Model → Configuration Models: holds (evidence: `Relay/Relay/State/AppModel.swift`)
- App Controller → App Model: creates (evidence: `Relay/Relay/State/AppController.swift`)
- App Controller → Hotkey Registration: configures (evidence: `Relay/Relay/State/AppController.swift`)
- App Model → Hotkey Registration: signals profile changes (evidence: `Relay/Relay/State/AppController.swift`)
- Hotkey Registration → KeyboardShortcuts: registers shortcuts (evidence: `Relay/Relay/Services/HotkeyRegistrationService.swift`)
- Hotkey Registration → Activation Service: dispatches bindings (evidence: `Relay/Relay/Services/HotkeyRegistrationService.swift`)
- Activation Service → Activation Decisions: selects action (evidence: `Relay/Relay/Services/AppActivationService.swift`)
- Activation Service → Target App Resolver: checks app state (evidence: `Relay/Relay/Services/AppActivationService.swift`)
- Activation Service → Frontmost Tracker: checks foreground (evidence: `Relay/Relay/Services/AppActivationService.swift`)
- Activation Service → Window Minimizer: controls windows (evidence: `Relay/Relay/Services/AppActivationService.swift`)
- Activation Service → macOS AppKit: launches and focuses (evidence: `README.md`)
- Window Minimizer → macOS AppKit: uses Accessibility (evidence: `README.md`)
- User → Data Settings: manages backups (evidence: `README.md`)
- Data Settings → App Model: reads configuration (evidence: `Relay/Relay/UI/DataSettingsView.swift`)
- Data Settings → Backup Service: imports and exports (evidence: `Relay/Relay/UI/DataSettingsView.swift`)
- Backup Service → Local Persistence: uses data directory (evidence: `Relay/Relay/Services/BackupService.swift`)
- User → Settings UI: changes settings (evidence: `README.md`)
- Settings UI → App Model: updates preferences
- Personalization UI → App Model: updates language choice (evidence: `Relay/Relay/UI/PersonalizationSettingsView.swift`)
- Personalization UI → Language Service: requests language change (evidence: `Relay/Relay/UI/PersonalizationSettingsView.swift`)
- App Controller → Login Item Service: applies login setting (evidence: `Relay/Relay/State/AppController.swift`)
- App Controller → Dock Icon Controller: applies Dock setting (evidence: `Relay/Relay/State/AppController.swift`)
