# jclee777/display-switch-lab architecture

> Architecture diagram of the GitHub repository jclee777/display-switch-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jclee777/display-switch-lab
- Repository: https://github.com/jclee777/display-switch-lab

## Overview

DisplaySwitchLab is a macOS menu-bar utility for choosing which built-in and external displays are enabled. The main workflow starts in the menu or global-shortcut panel, selects a mode, and delegates switching and recovery to the display model. The README also documents customizable shortcuts, login launch, localization, hot-plug recovery, and restoration on quit. Sampled code supports the model-to-switcher and persistence relationships; some implementation details are omitted, so uncertain wiring is not shown.

Main entry points: [`Sources/display-switch-lab/DisplaySwitchLabApp.swift`](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift) (Menu bar), [`Sources/display-switch-lab/DisplaySwitchModel.swift`](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift) (Display model), [`Sources/display-switch-lab/QuickSwitchPanel.swift`](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift) (Quick switch panel), [`Sources/display-switch-lab/Localization.swift`](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/Localization.swift) (Localization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_app["Application lifecycle"]
  node_menu["Menu bar"]
  node_panel["Quick switch panel"]
  node_hotkey["Global shortcut"]
  node_presentation["Shortcut and about UI"]
end

subgraph group_control["Switch control"]
  node_model["Display model"]
  node_session["Session recovery state"]
  node_watchdog["External display watchdog"]
end

subgraph group_platform["Display platform"]
  node_switcher["Display switcher"]
  node_inventory["Display inventory"]
  node_privateapi["Display enable API"]
  node_known[("Known display store")]
end

subgraph group_settings["Preferences"]
  node_shortcutprefs["Shortcut preferences"]
  node_login["Login launch setting"]
  node_localization["Localization<br/>[Localization.swift]"]
  node_strings["English and Chinese strings"]
end

node_user(("User"))
node_macos["macOS display services"]
node_loginservice["macOS login service"]

node_user -->|"chooses mode"| node_menu
node_user -->|"presses shortcut"| node_hotkey
node_menu -->|"applies mode"| node_model
node_menu -->|"opens panel"| node_panel
node_menu -->|"opens settings UI"| node_presentation
node_menu -->|"toggles launch"| node_login
node_hotkey -->|"loads shortcut"| node_shortcutprefs
node_hotkey -->|"opens or cycles"| node_panel
node_panel -->|"commits mode"| node_model
node_presentation -->|"saves shortcut"| node_shortcutprefs
node_app -->|"starts and restores"| node_model
node_app -->|"configures and stops"| node_panel
node_model -->|"tracks display state"| node_session
node_model -->|"queries and switches"| node_switcher
node_model -->|"arms recovery"| node_watchdog
node_switcher -->|"fetches displays"| node_inventory
node_switcher -->|"records and restores IDs"| node_known
node_switcher -->|"enables displays"| node_privateapi
node_inventory -->|"reads display state"| node_macos
node_privateapi -->|"configures displays"| node_macos
node_known -->|"stores display IDs"| node_macos
node_watchdog -->|"checks and restores"| node_switcher
node_shortcutprefs -->|"persists shortcut"| node_user
node_login -->|"registers service"| node_loginservice
node_menu -->|"gets interface text"| node_localization
node_panel -->|"gets interface text"| node_localization
node_presentation -->|"gets interface text"| node_localization
node_localization -->|"loads translations"| node_strings

click node_app "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift"
click node_menu "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift"
click node_panel "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift"
click node_hotkey "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift"
click node_presentation "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift"
click node_model "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_session "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_watchdog "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_switcher "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_inventory "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_privateapi "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_known "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_shortcutprefs "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift"
click node_login "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/LaunchAtLogin.swift"
click node_localization "https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/Localization.swift"
click node_strings "https://github.com/jclee777/display-switch-lab/tree/main/Sources/display-switch-lab/Resources"

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_menu,node_panel,node_hotkey,node_presentation,node_user toneBlue
class node_model,node_session,node_watchdog toneAmber
class node_switcher,node_inventory,node_privateapi,node_known toneMint
class node_shortcutprefs,node_login,node_localization,node_strings toneRose
class node_macos,node_loginservice toneIndigo
```

## Components

### App interface

- [Application lifecycle](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift): `Sources/display-switch-lab/DisplaySwitchLabApp.swift`
- [Menu bar](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift): `Sources/display-switch-lab/DisplaySwitchLabApp.swift`
- [Quick switch panel](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift): `Sources/display-switch-lab/QuickSwitchPanel.swift`
- [Global shortcut](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift): `Sources/display-switch-lab/QuickSwitchPanel.swift`
- [Shortcut and about UI](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift): `Sources/display-switch-lab/AppPreferences.swift`

### Switch control

- [Display model](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Session recovery state](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [External display watchdog](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`

### Display platform

- [Display switcher](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Display inventory](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Display enable API](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Known display store](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`

### Preferences

- [Shortcut preferences](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift): `Sources/display-switch-lab/AppPreferences.swift`
- [Login launch setting](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/LaunchAtLogin.swift): `Sources/display-switch-lab/LaunchAtLogin.swift`
- [Localization](https://github.com/jclee777/display-switch-lab/blob/main/Sources/display-switch-lab/Localization.swift): `Sources/display-switch-lab/Localization.swift`
- [English and Chinese strings](https://github.com/jclee777/display-switch-lab/tree/main/Sources/display-switch-lab/Resources): `Sources/display-switch-lab/Resources`

### Other components

- **User**
- **macOS display services**
- **macOS login service**

## Connections

- User → Menu bar: chooses mode
- User → Global shortcut: presses shortcut
- Menu bar → Display model: applies mode
- Menu bar → Quick switch panel: opens panel
- Menu bar → Shortcut and about UI: opens settings UI
- Menu bar → Login launch setting: toggles launch
- Global shortcut → Shortcut preferences: loads shortcut
- Global shortcut → Quick switch panel: opens or cycles
- Quick switch panel → Display model: commits mode
- Shortcut and about UI → Shortcut preferences: saves shortcut
- Application lifecycle → Display model: starts and restores
- Application lifecycle → Quick switch panel: configures and stops
- Display model → Session recovery state: tracks display state
- Display model → Display switcher: queries and switches
- Display model → External display watchdog: arms recovery
- Display switcher → Display inventory: fetches displays
- Display switcher → Known display store: records and restores IDs
- Display switcher → Display enable API: enables displays
- Display inventory → macOS display services: reads display state
- Display enable API → macOS display services: configures displays
- Known display store → macOS display services: stores display IDs
- External display watchdog → Display switcher: checks and restores
- Shortcut preferences → User: persists shortcut
- Login launch setting → macOS login service: registers service
- Menu bar → Localization: gets interface text
- Quick switch panel → Localization: gets interface text
- Shortcut and about UI → Localization: gets interface text
- Localization → English and Chinese strings: loads translations