# koekeishiya/yabai architecture

> Architecture diagram of the GitHub repository koekeishiya/yabai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koekeishiya/yabai
- Repository: https://github.com/koekeishiya/yabai

## Overview

Based on our analysis of the file tree and README, this project is a macOS tiling window manager (named “yabai”). Its purpose is to extend macOS’s built-in window management with a sophisticated tiling system based on a binary space partitioning algorithm, and it integrates with third‐party tools (like skhd) for keyboard shortcuts. The code is primarily in C (with some Objective-C in the “.m” files) and is organized into multiple source modules that manage displays, windows, spaces, and events.

##### Main Components
- Core Application & Entry Point – represented by files such as “src/application.c” and “src/yabai.c.”
- Event Handling System – include the event loop (“src/event_loop.c” and “src/event_signal.c”) which is responsible for polling and dispatching OS events.
- Managers for System Entities:
– Display Manager (“src/display_manager.c”) handling connected displays.
– Window Manager (“src/window_manager.c” along with “src/window.c” and “src/view.c”) that manages individual window operations.
– Space Manager (“src/space_manager.c” and “src/space.c”) to control workspaces/spaces.
– Process Manager (“src/process_manager.c”) managing system processes.
- Additional Functionality:
– Modules for Mission Control (“src/mission_control.c”) and message handling (“src/message.c”).
– “Rule” component (“src/rule.c”) that likely supports user-defined configurations for window handling.
- OS Integration:
– The “osax” directory contains the scripting additions (payloads, loaders) which interface directly with macOS system components.
- Utility and Helper Modules – under “src/misc” for logging, memory management, and other common helper functions.
- Build, Test, and Deployment:
– Makefile at the root, “scripts” for installation and code‐signing, and the “tests” directory for unit tests.

##### Relationships and Interactions
- A central “yabai Core” block (or main application block) that orchestrates control.
– the Event Handling component (which receives macOS events and dispatches them).
– the various managers (Display, Window, Space, Process) that process these events and interact with the system.
- External dependency nodes such as the Accessibility API and Screen Recording permission, marking them as prerequisites for certain components to function.

##### Important Architectural Patterns
- Use of the binary space partitioning algorithm for tiling window management (this could be annotated near the Window Manager).
- Modular structure where a central event loop dispatches work to specialized managers (e.g., display, window, space)—a pattern akin to the Reactor pattern.
- That the design leverages separation of concerns where OS integration (through “osax” and system-specific code) is kept distinct from the high-level logic.

##### Relevant Technologies and Frameworks
- That the project is written in C (and Objective-C for specific modules) and uses macOS-specific frameworks/APIs (like the Accessibility API and possibly CoreGraphics).

##### Final Advice
- Expand outwards to include the “osax” integration layer and external build/deployment systems.
- That all relevant components (from source-level utility libraries to the high-level modules) are included.

## Diagram (Mermaid)

```mermaid
graph TD
    OSEvents("OS Events (Accessibility,ScreenRecording)"):::external
    Core("yabai Core (Entry Point)"):::core
    EventHandling("Event Handling System"):::core

    subgraph "System Managers"
        DisplayManager("Display Manager"):::manager
        WindowManager("Window Manager (BSP Algorithm)"):::manager
        SpaceManager("Space Manager"):::manager
        ProcessManager("Process Manager"):::manager
    end

    MissionControl("Mission Control"):::manager
    MessageModule("Message Handling Module"):::manager
    RuleComponent("Rule Component"):::manager

    OSIntegration("OS Integration Layer (osax)"):::integration
    UtilityModules("Utility & Helper Modules"):::utility
    BuildDeployment("Build,Test,&Deployment"):::deployment

    OSEvents -->|"Generates"| Core
    Core -->|"Initializes"| EventHandling
    EventHandling -->|"Dispatches"| DisplayManager
    EventHandling -->|"Dispatches"| WindowManager
    EventHandling -->|"Dispatches"| SpaceManager
    EventHandling -->|"Dispatches"| ProcessManager
    EventHandling -->|"Notifies"| MessageModule
    Core -->|"Coordinates"| MissionControl
    Core -->|"Applies"| RuleComponent
    Core --- OSIntegration
    UtilityModules --- Core
    BuildDeployment -->|"Supports"| Core
    OSIntegration ---|"Interacts"| OSEvents

    classDef core fill:#ffe6f2,stroke:#cc0077,stroke-width:2px;
    classDef manager fill:#e6f2ff,stroke:#0077cc,stroke-width:2px;
    classDef integration fill:#e6ffe6,stroke:#009933,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#e6b800,stroke-width:2px;
    classDef utility fill:#f2e6ff,stroke:#9933cc,stroke-width:2px;
    classDef deployment fill:#fff0cc,stroke:#cc9900,stroke-width:2px;

click Core "https://github.com/koekeishiya/yabai/blob/master/src/application.c"
click Core "https://github.com/koekeishiya/yabai/blob/master/src/yabai.c"

click EventHandling "https://github.com/koekeishiya/yabai/blob/master/src/event_loop.c"
click EventHandling "https://github.com/koekeishiya/yabai/blob/master/src/event_signal.c"

click DisplayManager "https://github.com/koekeishiya/yabai/blob/master/src/display_manager.c"
click DisplayManager "https://github.com/koekeishiya/yabai/blob/master/src/display.c"
click DisplayManager "https://github.com/koekeishiya/yabai/blob/master/src/display.h"

click WindowManager "https://github.com/koekeishiya/yabai/blob/master/src/window_manager.c"
click WindowManager "https://github.com/koekeishiya/yabai/blob/master/src/window.c"
click WindowManager "https://github.com/koekeishiya/yabai/blob/master/src/view.c"

click SpaceManager "https://github.com/koekeishiya/yabai/blob/master/src/space_manager.c"
click SpaceManager "https://github.com/koekeishiya/yabai/blob/master/src/space.c"

click ProcessManager "https://github.com/koekeishiya/yabai/blob/master/src/process_manager.c"

click MissionControl "https://github.com/koekeishiya/yabai/blob/master/src/mission_control.c"

click MessageModule "https://github.com/koekeishiya/yabai/blob/master/src/message.c"

click RuleComponent "https://github.com/koekeishiya/yabai/blob/master/src/rule.c"

click OSIntegration "https://github.com/koekeishiya/yabai/tree/master/src/osax"

click UtilityModules "https://github.com/koekeishiya/yabai/tree/master/src/misc"

click BuildDeployment "https://github.com/koekeishiya/yabai/tree/master/makefile"
click BuildDeployment "https://github.com/koekeishiya/yabai/tree/master/scripts"
click BuildDeployment "https://github.com/koekeishiya/yabai/tree/master/tests"
```
