# lgug2z/komorebi architecture

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

- Interactive diagram: https://gitdiagram.com/lgug2z/komorebi
- Repository: https://github.com/lgug2z/komorebi

## Overview

Based on our analysis of the file tree and the detailed README, the project is a Rust-based tiling window manager for Windows called “komorebi”. Its purpose is to extend Windows’ native Desktop Window Manager (DWM) with tiling features and a rich CLI to control window arrangement, workspaces, animations, borders, and more. It is designed to integrate with external tools (like AutoHotKey and whkd) via IPC mechanisms (named pipes, Unix domain sockets, and even TCP) as well as a Rust client library for event subscriptions.

##### Main Components
- Core Engine ("komorebi"):
– Responsible for the core tiling logic, window management, workspace handling, monitor reconciliation, and integration with Windows APIs.
– Contains submodules like the Animation Manager, Border Manager, Focus Manager, Window Manager, and Workspace Reconciliator.
– Manages configuration (both static and dynamic, via JSON and CLI commands), and interfaces with the operating system (including DWM).

- Command-Line Interface (CLI) and Client Subsystem ("komorebic" and "komorebi-client"):
– Provides the CLI tools for users to control the window manager (e.g., commands like “start”, “stop”, “move-to-workspace”, “toggle-tiling”, etc.).
– Offers a subscription API (through named pipes, Unix domain sockets, and TCP) to relay events and state changes enabling integrations (demonstrated with example code in NodeJS and Rust).

- GUI Component ("komorebi-gui" and "komorebi-bar"):
– Offers a graphical status bar and possibly other UI elements that interact with the core engine.
– The “komorebi-bar” subproject (with its own modules like widget, render, config, etc.) displays information such as CPU, network, battery, and window-related data.

- Themes and Configurations ("komorebi-themes"):
– Contains design assets, theming logic, and configuration schemas (with JSON schemas provided) that allow customization of the window manager’s appearance and behavior.

- Documentation, Build, and Integration Assets:
– Extensive CLI documentation, workflow guides, and examples, which clarify how to integrate with third-party tools and how the IPC channels work.

##### Relationships and Interactions
- User Interaction Path:
– Users interact with the system via CLI commands (through “komorebic”) or via external GUI/statues (through “komorebi-bar” or “komorebi-gui”).
– These commands and events are passed to the core engine which then makes calls to the Windows API to manage windows and workspaces.

- IPC and Event Subscription:
– The core engine sends events (via window manager events, notifications, and socket messages) over named pipes, Unix domain sockets, or TCP.
– The “komorebi-client” crate and other subscriber tools receive these events and can build additional integrations or user-interface features.

- Modular and Extensible Design:
– Each subsystem (e.g., animations, borders, focus, window positioning) is implemented as a distinct module or sub-crate, facilitating easier maintenance, testing, and potential future refactoring.

##### Architectural Patterns and Design Principles
- Modular Design: Each major feature is isolated within its own module (e.g., core, animation, border manager, workspace, IPC subscribers) and even separate Cargo packages which encourages separation of concerns and reusability.
- Event-Driven Architecture: Events (such as window focus changes, workspace updates, and configuration reloads) are published and consumed via IPC channels, making the system reactive and extensible.
- Clear Separation Between API Layers: Distinguish between the external interface (CLI, GUI, and client libraries) and the internal core engine which deals with Windows-specific operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface & CLI Layer"
        CLI["Komorebic (CLI)"]:::cli
        GUI["Komorebi GUI"]:::gui
        BAR["Komorebi Bar"]:::gui
    end

    subgraph "Core Tiling Engine"
        WM["Window & Workspace Management"]:::core
        AM["Animation Manager"]:::core
        BM["Border Manager"]:::core
        FM["Focus Manager"]:::core
        TM["Theme Manager"]:::core
        SC["Static Config"]:::core
    end

    subgraph "IPC & Communication Layer"
        IPC["IPC Channels (NamedPipes,Sockets,TCP)"]:::ipc
        CLIENT["Komorebi Client (Event Subscription)"]:::ipc
    end

    subgraph "Themes & Assets"
        THEMES["Komorebi Themes"]:::themes
    end

    subgraph "Documentation & Integration"
        DOCS["General Documentation"]:::docs
        CLIDOCS["CLI Documentation"]:::docs
        AHK["AHK App Config"]:::docs
        AHKWF["AutoHotKey Workflow"]:::docs
    end

    WINAPI["Windows API"]:::ext

    %% User Interface to Core Engine
    CLI -->|"CommandInput"| WM
    GUI -->|"UICommand"| WM
    BAR -->|"UIStatus"| WM

    %% Core Engine internal module interactions
    WM -->|"Triggers"| AM
    WM -->|"Triggers"| BM
    WM -->|"Triggers"| FM
    WM -->|"Triggers"| TM
    WM -->|"Triggers"| SC

    %% Core Engine interactions with external systems
    WM -->|"Calls"| WINAPI
    WM -->|"PublishesEvents"| IPC
    TM -->|"Uses"| THEMES

    %% IPC Layer to Client Library
    IPC -->|"Notifies"| CLIENT

    %% Optional documentation references
    CLI -.->|"ReferDocs"| CLIDOCS
    CLI -.->|"ReferDocs"| DOCS

    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef cli fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef gui fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ipc fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef themes fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef docs fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
    classDef ext fill:#f0f0f0,stroke:#333,stroke-width:2px;

    click WM "https://github.com/lgug2z/komorebi/tree/master/komorebi/src/"
    click AM "https://github.com/lgug2z/komorebi/tree/master/komorebi/src/animation/"
    click BM "https://github.com/lgug2z/komorebi/tree/master/komorebi/src/border_manager/"
    click FM "https://github.com/lgug2z/komorebi/blob/master/komorebi/src/focus_manager.rs"
    click TM "https://github.com/lgug2z/komorebi/blob/master/komorebi/src/theme_manager.rs"
    click SC "https://github.com/lgug2z/komorebi/blob/master/komorebi/src/static_config.rs"
    click CLI "https://github.com/lgug2z/komorebi/blob/master/komorebic/src/main.rs"
    click CLIENT "https://github.com/lgug2z/komorebi/blob/master/komorebi-client/src/lib.rs"
    click BAR "https://github.com/lgug2z/komorebi/blob/master/komorebi-bar/src/main.rs"
    click GUI "https://github.com/lgug2z/komorebi/blob/master/komorebi-gui/src/main.rs"
    click THEMES "https://github.com/lgug2z/komorebi/blob/master/komorebi-themes/src/lib.rs"
    click CLIDOCS "https://github.com/lgug2z/komorebi/tree/master/docs/cli/"
    click DOCS "https://github.com/lgug2z/komorebi/tree/master/docs/"
    click AHK "https://github.com/lgug2z/komorebi/blob/master/docs/cli/ahk-app-specific-configuration.md"
    click AHKWF "https://github.com/lgug2z/komorebi/blob/master/docs/common-workflows/autohotkey.md"
```
