# zhmylove/korgwm architecture

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

- Interactive diagram: https://gitdiagram.com/zhmylove/korgwm
- Repository: https://github.com/zhmylove/korgwm

## Overview

korgwm is a Perl tiling window manager. Its principal workflow is managing X11 windows across screens and tags, with tiling or floating layouts, then responding to keyboard, mouse, and API control; a GTK panel presents status. The README documents additional EWMH, expose, notification, and plugin capabilities. Source excerpts were unavailable, so relationships are limited to documented runtime responsibilities rather than inferred module-to-module calls.

Main entry points: [`script/korgwm`](https://github.com/zhmylove/korgwm/blob/master/script/korgwm) (korgwm launcher), [`lib/X11/korgwm.pm`](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm.pm) (Window manager), [`lib/X11/korgwm/Hotkeys.pm`](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Hotkeys.pm) (Hotkeys), [`lib/X11/korgwm/Mouse.pm`](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Mouse.pm) (Mouse controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Window manager"]
  node_launcher["korgwm launcher"]
  node_manager["Window manager<br/>[korgwm.pm]"]
  node_config["YAML config<br/>[Config.pm]"]
  node_executor["Event loop<br/>[Executor.pm]"]
end

subgraph group_state["Windows and screens"]
  node_window["Window state<br/>[Window.pm]"]
  node_screen["Screen state<br/>[Screen.pm]"]
  node_tag["Tags<br/>[Tag.pm]"]
  node_layout["Layouts<br/>[Layout.pm]"]
  node_ewmh["EWMH support<br/>[EWMH.pm]"]
end

subgraph group_control["User control"]
  node_hotkeys["Hotkeys<br/>[Hotkeys.pm]"]
  node_mouse["Mouse controls<br/>[Mouse.pm]"]
  node_api["TCP API<br/>[API.pm]"]
  node_expose["Expose mode<br/>[Expose.pm]"]
end

subgraph group_display["Panel and integrations"]
  node_notifications["Notifications<br/>[Notifications.pm]"]
  node_panel["GTK panel<br/>[Panel.pm]"]
  node_battery["Battery plugin<br/>[Battery.pm]"]
  node_clock["Clock plugin<br/>[Clock.pm]"]
  node_lang["XKB language plugin<br/>[Lang.pm]"]
end

node_user(("User"))
node_xserver(("X11 server"))
node_dbus(("D-Bus"))

node_user -->|"starts"| node_launcher
node_launcher -->|"starts"| node_manager
node_manager -->|"controls X11"| node_xserver
node_user -->|"uses"| node_hotkeys
node_user -->|"uses"| node_mouse
node_user -->|"controls"| node_api
node_user -->|"switches windows"| node_expose
node_dbus -->|"sends notifications"| node_notifications

click node_launcher "https://github.com/zhmylove/korgwm/blob/master/script/korgwm"
click node_manager "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm.pm"
click node_config "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Config.pm"
click node_executor "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Executor.pm"
click node_window "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Window.pm"
click node_screen "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Screen.pm"
click node_tag "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Tag.pm"
click node_layout "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Layout.pm"
click node_ewmh "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/EWMH.pm"
click node_hotkeys "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Hotkeys.pm"
click node_mouse "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Mouse.pm"
click node_api "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/API.pm"
click node_expose "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Expose.pm"
click node_notifications "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Notifications.pm"
click node_panel "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel.pm"
click node_battery "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Battery.pm"
click node_clock "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Clock.pm"
click node_lang "https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Lang.pm"

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_launcher,node_manager,node_config,node_executor,node_user toneBlue
class node_window,node_screen,node_tag,node_layout,node_ewmh toneAmber
class node_hotkeys,node_mouse,node_api,node_expose,node_xserver toneMint
class node_notifications,node_panel,node_battery,node_clock,node_lang toneRose
class node_dbus toneIndigo
```

## Components

### Window manager

- [korgwm launcher](https://github.com/zhmylove/korgwm/blob/master/script/korgwm): `script/korgwm`
- [Window manager](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm.pm): `lib/X11/korgwm.pm`
- [YAML config](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Config.pm): `lib/X11/korgwm/Config.pm`
- [Event loop](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Executor.pm): `lib/X11/korgwm/Executor.pm`

### Windows and screens

- [Window state](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Window.pm): `lib/X11/korgwm/Window.pm`
- [Screen state](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Screen.pm): `lib/X11/korgwm/Screen.pm`
- [Tags](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Tag.pm): `lib/X11/korgwm/Tag.pm`
- [Layouts](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Layout.pm): `lib/X11/korgwm/Layout.pm`
- [EWMH support](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/EWMH.pm): `lib/X11/korgwm/EWMH.pm`

### User control

- [Hotkeys](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Hotkeys.pm): `lib/X11/korgwm/Hotkeys.pm`
- [Mouse controls](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Mouse.pm): `lib/X11/korgwm/Mouse.pm`
- [TCP API](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/API.pm): `lib/X11/korgwm/API.pm`
- [Expose mode](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Expose.pm): `lib/X11/korgwm/Expose.pm`

### Panel and integrations

- [Notifications](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Notifications.pm): `lib/X11/korgwm/Notifications.pm`
- [GTK panel](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel.pm): `lib/X11/korgwm/Panel.pm`
- [Battery plugin](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Battery.pm): `lib/X11/korgwm/Panel/Battery.pm`
- [Clock plugin](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Clock.pm): `lib/X11/korgwm/Panel/Clock.pm`
- [XKB language plugin](https://github.com/zhmylove/korgwm/blob/master/lib/X11/korgwm/Panel/Lang.pm): `lib/X11/korgwm/Panel/Lang.pm`

### Other components

- **User**
- **X11 server**
- **D-Bus**

## Connections

- User → korgwm launcher: starts
- korgwm launcher → Window manager: starts
- Window manager → X11 server: controls X11
- User → Hotkeys: uses
- User → Mouse controls: uses
- User → TCP API: controls
- User → Expose mode: switches windows
- D-Bus → Notifications: sends notifications