# denggw/display-switch-lab architecture

> Architecture diagram of the GitHub repository denggw/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/denggw/display-switch-lab
- Repository: https://github.com/denggw/display-switch-lab

## Overview

DisplaySwitchLab is a macOS menu-bar utility for choosing display layouts, with a global-shortcut floating panel as a second entry point. The user selects a machine-appropriate mode or force-restore action; the model coordinates display discovery, switching, and recovery. Screen-change monitoring and a watchdog support fallback recovery, while termination restores displays disabled during the session. The README documents bilingual UI and login-at-start support. The model excerpt is partial, so internal call links are limited to relationships visible in the excerpts and documented behavior.

Main entry points: [`Sources/display-switch-lab/DisplaySwitchModel.swift`](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift) (Display model), [`Sources/display-switch-lab/DisplaySwitchLabApp.swift`](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift) (Mode menu), [`Sources/display-switch-lab/QuickSwitchPanel.swift`](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift) (Quick switch panel), [`Sources/display-switch-lab/LaunchAtLogin.swift`](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/LaunchAtLogin.swift) (Login item)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_app["Menu bar app"]
  node_menu["Mode menu"]
  node_quick["Quick switch panel"]
  node_recorder["Shortcut recorder"]
end

subgraph group_switching["Display switching"]
  node_model["Display model"]
  node_mode["Mode selection"]
  node_switcher["Display switcher"]
  node_inventory["Display inventory"]
  node_privateapi["Display enable API"]
end

subgraph group_recovery["Recovery and state"]
  node_recoverylogic["Recovery watchdog"]
  node_known[("Known display store")]
  node_termination["Session restoration"]
end

subgraph group_settings["Preferences"]
  node_shortcutprefs["Shortcut preferences"]
  node_hotkey["Global hotkey"]
  node_login["Login item"]
  node_localization["Localization<br/>[Localization.swift]"]
end

node_user(("Mac user"))
node_system["macOS display system"]
node_servicemgmt["Service Management"]

node_user -->|"chooses mode"| node_menu
node_menu -->|"applies mode"| node_model
node_user -->|"uses shortcut"| node_quick
node_quick -->|"registers shortcut"| node_hotkey
node_quick -->|"commits selection"| node_model
node_menu -->|"requests restore"| node_model
node_model -->|"selects modes"| node_mode
node_model -->|"applies or fetches"| node_switcher
node_switcher -->|"fetches displays"| node_inventory
node_switcher -->|"records displays"| node_known
node_switcher -->|"configures displays"| node_privateapi
node_privateapi -->|"enables or disables"| node_system
node_system -->|"notifies screen changes"| node_model
node_model -->|"evaluates display state"| node_recoverylogic
node_recoverylogic -->|"restores displays"| node_switcher
node_recoverylogic -->|"reads known IDs"| node_known
node_app -->|"prepares quit"| node_termination
node_termination -->|"restores session displays"| node_switcher
node_recorder -->|"saves shortcut"| node_shortcutprefs
node_quick -->|"loads shortcut"| node_shortcutprefs
node_menu -->|"toggles login item"| node_login
node_login -->|"registers or unregisters"| node_servicemgmt
node_menu -->|"loads interface strings"| node_localization
node_quick -->|"loads interface strings"| node_localization

click node_app "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift"
click node_menu "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift"
click node_quick "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift"
click node_recorder "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift"
click node_model "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_mode "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_switcher "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_inventory "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_privateapi "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_recoverylogic "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_known "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_termination "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift"
click node_shortcutprefs "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift"
click node_hotkey "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift"
click node_login "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/LaunchAtLogin.swift"
click node_localization "https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/Localization.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_app,node_menu,node_quick,node_recorder,node_user toneBlue
class node_model,node_mode,node_switcher,node_inventory,node_privateapi toneAmber
class node_recoverylogic,node_known,node_termination toneMint
class node_shortcutprefs,node_hotkey,node_login,node_localization toneRose
class node_system,node_servicemgmt toneIndigo
```

## Components

### App interface

- [Menu bar app](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift): `Sources/display-switch-lab/DisplaySwitchLabApp.swift`
- [Mode menu](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchLabApp.swift): `Sources/display-switch-lab/DisplaySwitchLabApp.swift`
- [Quick switch panel](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift): `Sources/display-switch-lab/QuickSwitchPanel.swift`
- [Shortcut recorder](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift): `Sources/display-switch-lab/AppPreferences.swift`

### Display switching

- [Display model](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Mode selection](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Display switcher](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Display inventory](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Display enable API](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`

### Recovery and state

- [Recovery watchdog](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Known display store](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`
- [Session restoration](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/DisplaySwitchModel.swift): `Sources/display-switch-lab/DisplaySwitchModel.swift`

### Preferences

- [Shortcut preferences](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/AppPreferences.swift): `Sources/display-switch-lab/AppPreferences.swift`
- [Global hotkey](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/QuickSwitchPanel.swift): `Sources/display-switch-lab/QuickSwitchPanel.swift`
- [Login item](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/LaunchAtLogin.swift): `Sources/display-switch-lab/LaunchAtLogin.swift`
- [Localization](https://github.com/denggw/display-switch-lab/blob/main/Sources/display-switch-lab/Localization.swift): `Sources/display-switch-lab/Localization.swift`

### Other components

- **Mac user**
- **macOS display system**
- **Service Management**

## Connections

- Mac user → Mode menu: chooses mode
- Mode menu → Display model: applies mode
- Mac user → Quick switch panel: uses shortcut
- Quick switch panel → Global hotkey: registers shortcut
- Quick switch panel → Display model: commits selection
- Mode menu → Display model: requests restore
- Display model → Mode selection: selects modes
- Display model → Display switcher: applies or fetches
- Display switcher → Display inventory: fetches displays
- Display switcher → Known display store: records displays
- Display switcher → Display enable API: configures displays
- Display enable API → macOS display system: enables or disables
- macOS display system → Display model: notifies screen changes
- Display model → Recovery watchdog: evaluates display state
- Recovery watchdog → Display switcher: restores displays
- Recovery watchdog → Known display store: reads known IDs
- Menu bar app → Session restoration: prepares quit
- Session restoration → Display switcher: restores session displays
- Shortcut recorder → Shortcut preferences: saves shortcut
- Quick switch panel → Shortcut preferences: loads shortcut
- Mode menu → Login item: toggles login item
- Login item → Service Management: registers or unregisters
- Mode menu → Localization: loads interface strings
- Quick switch panel → Localization: loads interface strings