# glzr-io/glazewm architecture

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

- Interactive diagram: https://gitdiagram.com/glzr-io/glazewm
- Repository: https://github.com/glzr-io/glazewm

## Overview

##### Project type and purpose
-  GlazeWM is an **open-source, Rust-based tiling window manager for Windows**, inspired by i3wm.
-  It’s a **CLI-driven** application that runs as a background service, intercepts OS window events, applies user commands (via keybindings or CLI), and manages window layouts.

##### File structure
-  Top-level Cargo workspace:
- Cargo.toml, rust-toolchain.toml, rustfmt.toml
-  Crates under `packages/`:
- **wm**: core WM engine and IPC server
- **wm-cli**: command-line interface client
- **wm-common**: shared DTOs, types, utility functions
- **wm-ipc-client**: library for talking to wm’s IPC server
- **wm-platform**: platform abstraction (Win32/COM hooks, event listeners)
- **wm-watcher**: helper that watches for new processes/windows
-  CI/CD: GitHub workflows for lint, package, release

##### Extract insights from README
-  Describes user flow:
- Start GlazeWM (via installer or CLI)
- Load YAML config
- Spawn background process (`wm`)
- Intercept OS events, run user commands, update layout
- Optional: UI integration with Zebar via IPC
-  Key technologies:
- Rust/Cargo workspace
- Win32 hooks & COM (in `wm-platform`)
- Local IPC (likely named pipes or sockets)
- YAML configuration file
- WiX installer

##### Main components and their relationships
A. **Core WM Engine (`wm` crate)**
- Events In: OS window events (create, destroy, move, focus, etc.)
- Commands In: IPC messages from CLI or scripts
- Logic: manages tiling tree, workspaces, layout, window states
- Outputs: OS calls (move/resize windows), send events back via IPC

B. **Platform Abstraction (`wm-platform` crate)**
- Wraps Win32 APIs, COM event hooks, keyboard hooks
- Provides unified interfaces for tracking windows, monitors, input

C. **Common Types & Utilities (`wm-common` crate)**
- DTOs for windows, containers, workspaces
- IPC message formats, serialization
- Shared math/types (points, rectangles, deltas)

D. **IPC Layer**
- **Server**: built into `wm` (in `ipc_server.rs`)
- **Client**: `wm-ipc-client` library & `wm-cli` executable
- Communication: named pipes or local socket; request/response model

E. **CLI Tool (`wm-cli` crate)**
- Parses user-entered commands
- Sends IPC messages to the running WM server
- Useful for scripting or manual control

F. **Watcher Utility (`wm-watcher` crate)**
- A small binary that launches alongside `wm` to re-spawn or monitor
- May detect process crashes / new windows that require special handling

G. **Installer & Resources (`resources/`)**
- WiX XML files for MSIX/bundles
- Sample YAML config, PowerShell packaging scripts
- Logo, cheatsheet, service configuration

H. **Configuration File**
- YAML based
- Defines keybindings, layouts, workspaces, window rules, effects

##### Architectural Patterns and Design Principles
- **Layered Architecture**:
- Platform layer (`wm-platform`)
- Core logic layer (`wm`) + shared DTOs (`wm-common`)
- Interface layer (IPC, CLI)
- Delivery layer (installer, scripts)
- **Command Pattern**:
- Submodules under `wm/src/commands/...` implement individual window commands
- Each command is serialized over IPC and executed in the engine
- **Event-Driven**:
- OS generates events → platform layer → dispatch to core → produce side effects
- **Modular, Cargo Workspace**:
- Clear separation of concerns; easy to test/use each crate independently

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    OS["Windows OS"]:::external
    User["User (Keyboard)"]:::external

    %% Platform Layer
    subgraph "Platform Layer"
        Platform["wm-platform: Win32 hooks & COM"]:::platform
    end

    %% Core WM Engine
    subgraph "Core WM Engine"
        subgraph "packages/wm"
            WMMain["main.rs"]:::core
            WMCore["wm.rs"]:::core
            IPCServer["ipc_server.rs"]:::core
            Commands["Command Modules"]:::core
            Events["Event Modules"]:::core
            Models["Model Modules"]:::core
            UserConfig["user_config.rs"]:::core
        end
    end

    %% Common Types & Utilities
    Common["wm-common: DTOs & Utils"]:::common

    %% Interface Layer
    subgraph "Interface Layer"
        CLI["wm-cli: IPC client"]:::interface
        IPCCli["wm-ipc-client: Library"]:::interface
    end

    %% Watcher Utility
    Watcher["wm-watcher: Watcher Utility"]:::interface

    %% Resources & Installer
    Resources["Resources: installer, scripts, sample config"]:::resource

    %% Data Flows
    OS -->|"Win32 API calls & events"| Platform
    User -->|"Keyboard hooks"| Platform
    Platform -->|"Dispatch events"| WMMain
    Common -->|"Shared DTOs & IPC formats"| WMMain
    Common -->|"Shared DTOs & IPC formats"| Platform
    CLI -->|"Named Pipe IPC"| IPCServer
    IPCCli -->|"Library IPC calls"| IPCServer
    IPCServer -->|"Handle requests"| WMMain
    WMMain -->|"Manage layout & state"| WMCore
    WMCore -->|"Invoke platform APIs"| Platform
    WMMain -->|"OS window calls"| OS
    Watcher -.->|"Monitors & restarts"| Platform
    Watcher -.->|"Monitors & restarts"| WMMain
    Resources -->|"Installs binaries & configs"| WMMain

    %% Click Events
    click Platform "https://github.com/glzr-io/glazewm/tree/main/packages/wm-platform/"
    click WMMain "https://github.com/glzr-io/glazewm/blob/main/packages/wm/src/main.rs"
    click WMCore "https://github.com/glzr-io/glazewm/blob/main/packages/wm/src/wm.rs"
    click IPCServer "https://github.com/glzr-io/glazewm/blob/main/packages/wm/src/ipc_server.rs"
    click Commands "https://github.com/glzr-io/glazewm/tree/main/packages/wm/src/commands/"
    click Events "https://github.com/glzr-io/glazewm/tree/main/packages/wm/src/events/"
    click Models "https://github.com/glzr-io/glazewm/tree/main/packages/wm/src/models/"
    click UserConfig "https://github.com/glzr-io/glazewm/blob/main/packages/wm/src/user_config.rs"
    click Common "https://github.com/glzr-io/glazewm/tree/main/packages/wm-common/"
    click IPCCli "https://github.com/glzr-io/glazewm/blob/main/packages/wm-ipc-client/src/lib.rs"
    click CLI "https://github.com/glzr-io/glazewm/blob/main/packages/wm-cli/src/main.rs"
    click Watcher "https://github.com/glzr-io/glazewm/blob/main/packages/wm-watcher/src/main.rs"
    click Resources "https://github.com/glzr-io/glazewm/tree/main/resources/"

    %% Styles
    classDef platform fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef common fill:#fff3cd,stroke:#856404,color:#856404;
    classDef interface fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef resource fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
