# nikitabobko/aerospace architecture

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

- Interactive diagram: https://gitdiagram.com/nikitabobko/aerospace
- Repository: https://github.com/nikitabobko/aerospace

## Overview

AeroSpace is an i3-like tiling window manager for macOS. Its principal workflow is a user or CLI client issuing a command, which the app server parses and executes against a tree of workspaces, monitors, and windows; layout and focus changes are applied through macOS accessibility APIs. Plain-text configuration, hotkeys, mouse interaction, event subscriptions, and the menu bar are significant supporting capabilities. The graph uses README statements and shown source/index references; unsampled implementation links are omitted or marked unverified.

Main entry points: [`Sources/AppBundle/server.swift`](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/server.swift) (Unix socket server), [`Sources/AppBundle/command/impl`](https://github.com/nikitabobko/aerospace/tree/main/Sources/AppBundle/command/impl) (Command handlers), [`Sources/AppBundle/tree/Window.swift`](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/Window.swift) (Window model), [`Sources/AppBundle/tree/TreeNode.swift`](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/TreeNode.swift) (Window tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_cli["CLI client<br/>[_main.swift]"]
  node_menu["Menu bar UI"]
end

subgraph group_runtime["Command Runtime"]
  node_socket["Unix socket server<br/>[server.swift]"]
  node_parser["Command parsing<br/>[parseCommand.swift]"]
  node_commands["Command handlers"]
  node_shell["Shell combinators<br/>[Shell.swift]"]
  node_format["Output formatting<br/>[format.swift]"]
  node_subscriptions["Event subscriptions"]
end

subgraph group_config["Configuration"]
  node_config["Config loading<br/>[ConfigFile.swift]"]
  node_bindings["Hotkey bindings"]
  node_watcher["Config watcher"]
end

subgraph group_wm["Window Management"]
  node_tree["Window tree<br/>[TreeNode.swift]"]
  node_workspace["Virtual workspaces<br/>[Workspace.swift]"]
  node_window["Window model<br/>[Window.swift]"]
  node_layout["Tiling layout"]
  node_focus["Focus management<br/>[focus.swift]"]
  node_mouse["Mouse controls<br/>[mouse.swift]"]
end

subgraph group_macos["macOS Integration"]
  node_app["App lifecycle<br/>[MacApp.swift]"]
  node_accessibility["Accessibility adapter"]
  node_observer["Global observer"]
end

node_user(("User"))
node_macos(("macOS"))

node_user -->|"issues commands"| node_cli
node_user -->|"uses status menu"| node_menu
node_cli -->|"sends requests"| node_socket
node_socket -->|"parses commands"| node_parser
node_socket -->|"runs handlers"| node_commands
node_shell -->|"runs commands"| node_commands
node_commands -->|"formats results"| node_format
node_config -.->|"defines mappings"| node_bindings
node_watcher -.->|"reloads config"| node_config
node_commands -.->|"changes tree"| node_tree
node_workspace -->|"forms tree nodes"| node_tree
node_window -->|"forms tree nodes"| node_tree
node_layout -->|"reads tree"| node_tree
node_layout -->|"lays out workspaces"| node_workspace
node_layout -->|"positions windows"| node_window
node_focus -.->|"focuses windows"| node_window
node_mouse -.->|"controls focus"| node_focus
node_app -->|"manages windows"| node_window
node_app -.->|"uses accessibility"| node_accessibility
node_observer -.->|"observes apps"| node_app
node_socket -->|"dispatches subscriptions"| node_subscriptions
node_macos -->|"provides APIs"| node_accessibility
node_menu -->|"shows workspace state"| node_workspace

click node_cli "https://github.com/nikitabobko/aerospace/blob/main/Sources/Cli/_main.swift"
click node_menu "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/ui/TrayMenuModel.swift"
click node_socket "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/server.swift"
click node_parser "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/command/parseCommand.swift"
click node_commands "https://github.com/nikitabobko/aerospace/tree/main/Sources/AppBundle/command/impl"
click node_shell "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/shell/Shell.swift"
click node_format "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/command/format.swift"
click node_config "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/ConfigFile.swift"
click node_bindings "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/HotkeyBinding.swift"
click node_watcher "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/ConfigFileWatcher.swift"
click node_tree "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/TreeNode.swift"
click node_workspace "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/Workspace.swift"
click node_window "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/Window.swift"
click node_layout "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/layout/layoutRecursive.swift"
click node_focus "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/focus.swift"
click node_mouse "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/mouse/mouse.swift"
click node_app "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/MacApp.swift"
click node_accessibility "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/util/accessibility.swift"
click node_observer "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/GlobalObserver.swift"
click node_subscriptions "https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/subscriptions.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_cli,node_menu,node_user toneBlue
class node_socket,node_parser,node_commands,node_shell,node_format,node_subscriptions toneAmber
class node_config,node_bindings,node_watcher toneMint
class node_tree,node_workspace,node_window,node_layout,node_focus,node_mouse toneRose
class node_app,node_accessibility,node_observer,node_macos toneIndigo
```

## Components

### User Interfaces

- [CLI client](https://github.com/nikitabobko/aerospace/blob/main/Sources/Cli/_main.swift): `Sources/Cli/_main.swift`
- [Menu bar UI](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/ui/TrayMenuModel.swift): `Sources/AppBundle/ui/TrayMenuModel.swift`

### Command Runtime

- [Unix socket server](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/server.swift): `Sources/AppBundle/server.swift`
- [Command parsing](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/command/parseCommand.swift): `Sources/AppBundle/command/parseCommand.swift`
- [Command handlers](https://github.com/nikitabobko/aerospace/tree/main/Sources/AppBundle/command/impl): `Sources/AppBundle/command/impl`
- [Shell combinators](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/shell/Shell.swift): `Sources/AppBundle/shell/Shell.swift`
- [Output formatting](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/command/format.swift): `Sources/AppBundle/command/format.swift`
- [Event subscriptions](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/subscriptions.swift): `Sources/AppBundle/subscriptions.swift`

### Configuration

- [Config loading](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/ConfigFile.swift): `Sources/AppBundle/config/ConfigFile.swift`
- [Hotkey bindings](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/HotkeyBinding.swift): `Sources/AppBundle/config/HotkeyBinding.swift`
- [Config watcher](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/config/ConfigFileWatcher.swift): `Sources/AppBundle/config/ConfigFileWatcher.swift`

### Window Management

- [Window tree](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/TreeNode.swift): `Sources/AppBundle/tree/TreeNode.swift`
- [Virtual workspaces](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/Workspace.swift): `Sources/AppBundle/tree/Workspace.swift`
- [Window model](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/Window.swift): `Sources/AppBundle/tree/Window.swift`
- [Tiling layout](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/layout/layoutRecursive.swift): `Sources/AppBundle/layout/layoutRecursive.swift`
- [Focus management](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/focus.swift): `Sources/AppBundle/focus.swift`
- [Mouse controls](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/mouse/mouse.swift): `Sources/AppBundle/mouse/mouse.swift`

### macOS Integration

- [App lifecycle](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/tree/MacApp.swift): `Sources/AppBundle/tree/MacApp.swift`
- [Accessibility adapter](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/util/accessibility.swift): `Sources/AppBundle/util/accessibility.swift`
- [Global observer](https://github.com/nikitabobko/aerospace/blob/main/Sources/AppBundle/GlobalObserver.swift): `Sources/AppBundle/GlobalObserver.swift`

### Other components

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

## Connections

- User → CLI client: issues commands (evidence: `README.md`)
- User → Menu bar UI: uses status menu (evidence: `README.md`)
- CLI client → Unix socket server: sends requests (evidence: `Sources/Cli/_main.swift`)
- Unix socket server → Command parsing: parses commands (evidence: `Sources/AppBundle/server.swift`)
- Unix socket server → Command handlers: runs handlers (evidence: `Sources/AppBundle/server.swift`)
- Shell combinators → Command handlers: runs commands (evidence: `Sources/AppBundle/shell/Shell.swift`)
- Command handlers → Output formatting: formats results (evidence: `Sources/AppBundle/command/format.swift`)
- Config loading → Hotkey bindings: defines mappings
- Config watcher → Config loading: reloads config
- Command handlers → Window tree: changes tree
- Virtual workspaces → Window tree: forms tree nodes (evidence: `Sources/AppBundle/tree/Workspace.swift`)
- Window model → Window tree: forms tree nodes (evidence: `Sources/AppBundle/tree/Window.swift`)
- Tiling layout → Window tree: reads tree (evidence: `Sources/AppBundle/layout/layoutRecursive.swift`)
- Tiling layout → Virtual workspaces: lays out workspaces (evidence: `Sources/AppBundle/layout/layoutRecursive.swift`)
- Tiling layout → Window model: positions windows (evidence: `Sources/AppBundle/layout/layoutRecursive.swift`)
- Focus management → Window model: focuses windows
- Mouse controls → Focus management: controls focus
- App lifecycle → Window model: manages windows (evidence: `Sources/AppBundle/tree/MacApp.swift`)
- App lifecycle → Accessibility adapter: uses accessibility
- Global observer → App lifecycle: observes apps
- Unix socket server → Event subscriptions: dispatches subscriptions (evidence: `Sources/AppBundle/server.swift`)
- macOS → Accessibility adapter: provides APIs (evidence: `README.md`)
- Menu bar UI → Virtual workspaces: shows workspace state (evidence: `Sources/AppBundle/ui/TrayMenuModel.swift`)
