# mrkai77/loop architecture

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

- Interactive diagram: https://gitdiagram.com/mrkai77/loop
- Repository: https://github.com/mrkai77/loop

## Overview

Loop is a macOS window-management app. Users trigger actions with a keybind, mouse gesture, radial menu, or URL command; Loop resolves the target window and action, then applies the requested layout or movement. The README also documents previews, cycles, stashing, and extensive customization. The graph follows documented capabilities and sampled call sites; unsampled subsystem internals are represented only where their paths are present in the tree, and uncertain wiring is omitted.

Main entry points: [`Loop/Core/LoopManager.swift`](https://github.com/mrkai77/loop/blob/develop/Loop/Core/LoopManager.swift) (App coordinator), [`Loop/Window Management/Window Manipulation/WindowActionEngine.swift`](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Manipulation/WindowActionEngine.swift) (Action dispatcher), [`Loop/Stashing/StashManager.swift`](https://github.com/mrkai77/loop/blob/develop/Loop/Stashing/StashManager.swift) (Stash manager), [`Loop/Window Management/Window/Window.swift`](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window/Window.swift) (Window access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Inputs and runtime"]
  node_url["URL commands"]
  node_loop["App coordinator<br/>[LoopManager.swift]"]
  node_triggers["Input triggers"]
  node_mouse["Mouse observer"]
  node_accessibility["Accessibility access"]
end

subgraph group_actions["Window actions"]
  node_actionspec["Action definitions<br/>[WindowAction.swift]"]
  node_cycle["Cycle actions"]
  node_engine["Action dispatcher"]
  node_windowengine["Window layout engine<br/>[WindowEngine.swift]"]
  node_window["Window access<br/>[Window.swift]"]
  node_drag["Drag snapping"]
end

subgraph group_workspace["Workspace features"]
  node_radial["Radial menu"]
  node_preview["Action preview"]
  node_stash["Stash manager<br/>[StashManager.swift]"]
  node_stashstore[("Stashed windows")]
end

subgraph group_settings["Settings and appearance"]
  node_settings["Settings UI"]
  node_accent["Accent colors"]
  node_wallpaper["Wallpaper analysis"]
end

subgraph group_updates["Updates"]
  node_updater["Update workflow<br/>[Updater.swift]"]
  node_updateui["Update interface<br/>[UpdateView.swift]"]
  node_installer["Privileged installer"]
end

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

node_user -->|"presses keys"| node_triggers
node_user -->|"moves cursor"| node_mouse
node_user -->|"opens command"| node_url
node_triggers -->|"dispatches input"| node_loop
node_mouse -->|"dispatches input"| node_loop
node_url -->|"dispatches command"| node_loop
node_loop -->|"resolves action"| node_actionspec
node_loop -->|"applies action"| node_engine
node_loop -->|"presents menu"| node_radial
node_loop -->|"presents preview"| node_preview
node_loop -->|"coordinates cycles"| node_cycle
node_cycle -->|"applies cycle step"| node_engine
node_radial -->|"selects direction"| node_loop
node_engine -->|"routes resize"| node_windowengine
node_engine -->|"targets window"| node_window
node_windowengine -->|"resizes window"| node_window
node_window -->|"reads and sets frames"| node_macos
node_user -->|"drags window"| node_drag
node_drag -->|"applies snap"| node_engine
node_windowengine -->|"notifies resize"| node_stash
node_drag -->|"notifies manipulation"| node_stash
node_stash -->|"reads and updates"| node_stashstore
node_stash -->|"moves stashed window"| node_window
node_user -->|"configures features"| node_settings
node_settings -->|"sets color preferences"| node_accent
node_accent -->|"fetches colors"| node_wallpaper
node_accessibility -->|"checks permission"| node_macos
node_user -->|"reviews update"| node_updateui
node_updateui -->|"requests update"| node_updater
node_updater -.->|"requests installation"| node_installer

click node_url "https://github.com/mrkai77/loop/blob/develop/Loop/Core/URLCommandHandler.swift"
click node_loop "https://github.com/mrkai77/loop/blob/develop/Loop/Core/LoopManager.swift"
click node_triggers "https://github.com/mrkai77/loop/blob/develop/Loop/Core/Observers/KeybindTrigger.swift"
click node_mouse "https://github.com/mrkai77/loop/blob/develop/Loop/Core/Observers/MouseInteractionObserver.swift"
click node_actionspec "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Action/WindowAction.swift"
click node_cycle "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Action/CycleActionCoordinator.swift"
click node_engine "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Manipulation/WindowActionEngine.swift"
click node_windowengine "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Manipulation/WindowEngine.swift"
click node_window "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window/Window.swift"
click node_drag "https://github.com/mrkai77/loop/blob/develop/Loop/Core/WindowDragManager.swift"
click node_radial "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Action%20Indicators/Radial%20Menu/RadialMenuController.swift"
click node_preview "https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Action%20Indicators/Preview%20Window/PreviewController.swift"
click node_stash "https://github.com/mrkai77/loop/blob/develop/Loop/Stashing/StashManager.swift"
click node_stashstore "https://github.com/mrkai77/loop/blob/develop/Loop/Stashing/StashedWindowStore.swift"
click node_settings "https://github.com/mrkai77/loop/blob/develop/Loop/Settings%20Window/SettingsWindowManager.swift"
click node_accent "https://github.com/mrkai77/loop/blob/develop/Loop/Accent%20Color/AccentColorController.swift"
click node_wallpaper "https://github.com/mrkai77/loop/blob/develop/Loop/Accent%20Color/WallpaperProcessor.swift"
click node_accessibility "https://github.com/mrkai77/loop/blob/develop/Loop/Utilities/AccessibilityManager.swift"
click node_updater "https://github.com/mrkai77/loop/blob/develop/Loop/Updater/Updater.swift"
click node_updateui "https://github.com/mrkai77/loop/blob/develop/Loop/Updater/Views/UpdateView.swift"
click node_installer "https://github.com/mrkai77/loop/blob/develop/LoopUpdaterHelper/PrivilegedInstallerService.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_url,node_loop,node_triggers,node_mouse,node_accessibility,node_user toneBlue
class node_actionspec,node_cycle,node_engine,node_windowengine,node_window,node_drag toneAmber
class node_radial,node_preview,node_stash,node_stashstore toneMint
class node_settings,node_accent,node_wallpaper toneRose
class node_updater,node_updateui,node_installer,node_macos toneIndigo
```

## Components

### Inputs and runtime

- [URL commands](https://github.com/mrkai77/loop/blob/develop/Loop/Core/URLCommandHandler.swift): `Loop/Core/URLCommandHandler.swift`
- [App coordinator](https://github.com/mrkai77/loop/blob/develop/Loop/Core/LoopManager.swift): `Loop/Core/LoopManager.swift`
- [Input triggers](https://github.com/mrkai77/loop/blob/develop/Loop/Core/Observers/KeybindTrigger.swift): `Loop/Core/Observers/KeybindTrigger.swift`
- [Mouse observer](https://github.com/mrkai77/loop/blob/develop/Loop/Core/Observers/MouseInteractionObserver.swift): `Loop/Core/Observers/MouseInteractionObserver.swift`
- [Accessibility access](https://github.com/mrkai77/loop/blob/develop/Loop/Utilities/AccessibilityManager.swift): `Loop/Utilities/AccessibilityManager.swift`

### Window actions

- [Action definitions](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Action/WindowAction.swift): `Loop/Window Management/Window Action/WindowAction.swift`
- [Cycle actions](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Action/CycleActionCoordinator.swift): `Loop/Window Management/Window Action/CycleActionCoordinator.swift`
- [Action dispatcher](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Manipulation/WindowActionEngine.swift): `Loop/Window Management/Window Manipulation/WindowActionEngine.swift`
- [Window layout engine](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window%20Manipulation/WindowEngine.swift): `Loop/Window Management/Window Manipulation/WindowEngine.swift`
- [Window access](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Management/Window/Window.swift): `Loop/Window Management/Window/Window.swift`
- [Drag snapping](https://github.com/mrkai77/loop/blob/develop/Loop/Core/WindowDragManager.swift): `Loop/Core/WindowDragManager.swift`

### Workspace features

- [Radial menu](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Action%20Indicators/Radial%20Menu/RadialMenuController.swift): `Loop/Window Action Indicators/Radial Menu/RadialMenuController.swift`
- [Action preview](https://github.com/mrkai77/loop/blob/develop/Loop/Window%20Action%20Indicators/Preview%20Window/PreviewController.swift): `Loop/Window Action Indicators/Preview Window/PreviewController.swift`
- [Stash manager](https://github.com/mrkai77/loop/blob/develop/Loop/Stashing/StashManager.swift): `Loop/Stashing/StashManager.swift`
- [Stashed windows](https://github.com/mrkai77/loop/blob/develop/Loop/Stashing/StashedWindowStore.swift): `Loop/Stashing/StashedWindowStore.swift`

### Settings and appearance

- [Settings UI](https://github.com/mrkai77/loop/blob/develop/Loop/Settings%20Window/SettingsWindowManager.swift): `Loop/Settings Window/SettingsWindowManager.swift`
- [Accent colors](https://github.com/mrkai77/loop/blob/develop/Loop/Accent%20Color/AccentColorController.swift): `Loop/Accent Color/AccentColorController.swift`
- [Wallpaper analysis](https://github.com/mrkai77/loop/blob/develop/Loop/Accent%20Color/WallpaperProcessor.swift): `Loop/Accent Color/WallpaperProcessor.swift`

### Updates

- [Update workflow](https://github.com/mrkai77/loop/blob/develop/Loop/Updater/Updater.swift): `Loop/Updater/Updater.swift`
- [Update interface](https://github.com/mrkai77/loop/blob/develop/Loop/Updater/Views/UpdateView.swift): `Loop/Updater/Views/UpdateView.swift`
- [Privileged installer](https://github.com/mrkai77/loop/blob/develop/LoopUpdaterHelper/PrivilegedInstallerService.swift): `LoopUpdaterHelper/PrivilegedInstallerService.swift`

### Other components

- **User**
- **macOS windows**

## Connections

- User → Input triggers: presses keys
- User → Mouse observer: moves cursor
- User → URL commands: opens command
- Input triggers → App coordinator: dispatches input
- Mouse observer → App coordinator: dispatches input
- URL commands → App coordinator: dispatches command
- App coordinator → Action definitions: resolves action
- App coordinator → Action dispatcher: applies action
- App coordinator → Radial menu: presents menu
- App coordinator → Action preview: presents preview
- App coordinator → Cycle actions: coordinates cycles
- Cycle actions → Action dispatcher: applies cycle step
- Radial menu → App coordinator: selects direction
- Action dispatcher → Window layout engine: routes resize
- Action dispatcher → Window access: targets window
- Window layout engine → Window access: resizes window
- Window access → macOS windows: reads and sets frames
- User → Drag snapping: drags window
- Drag snapping → Action dispatcher: applies snap
- Window layout engine → Stash manager: notifies resize
- Drag snapping → Stash manager: notifies manipulation
- Stash manager → Stashed windows: reads and updates
- Stash manager → Window access: moves stashed window
- User → Settings UI: configures features
- Settings UI → Accent colors: sets color preferences
- Accent colors → Wallpaper analysis: fetches colors
- Accessibility access → macOS windows: checks permission
- User → Update interface: reviews update
- Update interface → Update workflow: requests update
- Update workflow → Privileged installer: requests installation