# noctalia-dev/umbriel architecture

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

- Interactive diagram: https://gitdiagram.com/noctalia-dev/umbriel
- Repository: https://github.com/noctalia-dev/umbriel

## Overview

Umbriel is a Wayland compositor. Its principal workflow is to start a compositor backend, accept client and input events, manage windows in per-output workspaces and layouts, then present the resulting scene on configured outputs. The graph also covers documented configuration, effects, IPC, overview, locking, and Xwayland capabilities. Some links reflect documented capabilities or source-index imports rather than inspected call sites; unsampled implementation details are not asserted.

Main entry points: [`src/server/server.cpp`](https://github.com/noctalia-dev/umbriel/blob/main/src/server/server.cpp) (Compositor server), [`src/workspace/workspace.cpp`](https://github.com/noctalia-dev/umbriel/blob/main/src/workspace/workspace.cpp) (Workspace manager), [`src/input/cursor.cpp`](https://github.com/noctalia-dev/umbriel/blob/main/src/input/cursor.cpp) (Pointer and cursor), [`src/main.cpp`](https://github.com/noctalia-dev/umbriel/blob/main/src/main.cpp) (CLI and startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Compositor runtime"]
  node_main["CLI and startup<br/>[main.cpp]"]
  node_server["Compositor server<br/>[server.cpp]"]
  node_backend["Backend manager"]
  node_xwayland["Xwayland support<br/>[xwayland.cpp]"]
  node_session_lock["Session lock<br/>[session_lock.cpp]"]
end

subgraph group_windows["Windows and workspaces"]
  node_workspace["Workspace manager<br/>[workspace.cpp]"]
  node_view["Window views<br/>[view.h]"]
  node_layouts["Window layouts<br/>[layout.h]"]
  node_scratchpad["Scratchpads<br/>[scratchpad.cpp]"]
end

subgraph group_interaction["Input and interaction"]
  node_cursor["Pointer and cursor<br/>[cursor.cpp]"]
  node_seat["Input seat<br/>[seat.h]"]
  node_overview["Workspace overview<br/>[overview.cpp]"]
end

subgraph group_display["Display and effects"]
  node_output["Output management<br/>[output.cpp]"]
  node_effects["Effect registry"]
  node_renderer["Scene renderer<br/>[fx_pass.c]"]
end

subgraph group_operations["Configuration and control"]
  node_config["Configuration<br/>[config.h]"]
  node_resolver["Config resolution<br/>[resolve.cpp]"]
  node_ipc["IPC commands<br/>[ipc_commands.cpp]"]
  node_ipc_client["IPC client<br/>[ipc_client.cpp]"]
end

node_user(("Desktop user"))
node_wayland_clients(("Wayland clients"))
node_wlroots["wlroots"]

node_user -->|"starts session"| node_main
node_main -->|"starts server"| node_server
node_server -->|"selects backend"| node_backend
node_server -->|"loads configuration"| node_config
node_server -->|"resolves settings"| node_resolver
node_wayland_clients -->|"connect"| node_server
node_server -->|"uses compositor APIs"| node_wlroots
node_server -->|"provides IPC"| node_ipc
node_user -->|"runs commands"| node_ipc_client
node_ipc_client -->|"sends commands"| node_ipc
node_server -->|"handles input"| node_cursor
node_cursor -->|"uses seat"| node_seat
node_cursor -->|"routes interaction"| node_overview
node_workspace -->|"uses layouts"| node_layouts
node_workspace -->|"manages windows"| node_view
node_workspace -->|"associates outputs"| node_output
node_user -->|"summons groups"| node_scratchpad
node_server -->|"supports locking"| node_session_lock
node_server -->|"supports X11 clients"| node_xwayland
node_output -->|"applies effects"| node_effects
node_effects -.->|"selects scene effects"| node_renderer
node_renderer -.->|"extends scene rendering"| node_wlroots

click node_main "https://github.com/noctalia-dev/umbriel/blob/main/src/main.cpp"
click node_server "https://github.com/noctalia-dev/umbriel/blob/main/src/server/server.cpp"
click node_backend "https://github.com/noctalia-dev/umbriel/blob/main/src/server/backend_manager.cpp"
click node_xwayland "https://github.com/noctalia-dev/umbriel/blob/main/src/xwayland/xwayland.cpp"
click node_config "https://github.com/noctalia-dev/umbriel/blob/main/src/config/config.h"
click node_resolver "https://github.com/noctalia-dev/umbriel/blob/main/src/config/resolve.cpp"
click node_ipc "https://github.com/noctalia-dev/umbriel/blob/main/src/server/ipc_commands.cpp"
click node_ipc_client "https://github.com/noctalia-dev/umbriel/blob/main/src/cli/ipc_client.cpp"
click node_cursor "https://github.com/noctalia-dev/umbriel/blob/main/src/input/cursor.cpp"
click node_seat "https://github.com/noctalia-dev/umbriel/blob/main/src/input/seat.h"
click node_overview "https://github.com/noctalia-dev/umbriel/blob/main/src/overview/overview.cpp"
click node_workspace "https://github.com/noctalia-dev/umbriel/blob/main/src/workspace/workspace.cpp"
click node_view "https://github.com/noctalia-dev/umbriel/blob/main/src/view/view.h"
click node_layouts "https://github.com/noctalia-dev/umbriel/blob/main/src/layout/layout.h"
click node_scratchpad "https://github.com/noctalia-dev/umbriel/blob/main/src/workspace/scratchpad.cpp"
click node_output "https://github.com/noctalia-dev/umbriel/blob/main/src/output/output.cpp"
click node_effects "https://github.com/noctalia-dev/umbriel/blob/main/src/scene/effect_registry.cpp"
click node_renderer "https://github.com/noctalia-dev/umbriel/blob/main/umbrielfx/render/fx_renderer/fx_pass.c"
click node_session_lock "https://github.com/noctalia-dev/umbriel/blob/main/src/lock/session_lock.cpp"

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_main,node_server,node_backend,node_xwayland,node_session_lock,node_user,node_wayland_clients toneBlue
class node_workspace,node_view,node_layouts,node_scratchpad toneAmber
class node_cursor,node_seat,node_overview toneMint
class node_output,node_effects,node_renderer toneRose
class node_config,node_resolver,node_ipc,node_ipc_client,node_wlroots toneIndigo
```

## Components

### Compositor runtime

- [CLI and startup](https://github.com/noctalia-dev/umbriel/blob/main/src/main.cpp): `src/main.cpp`
- [Compositor server](https://github.com/noctalia-dev/umbriel/blob/main/src/server/server.cpp): `src/server/server.cpp`
- [Backend manager](https://github.com/noctalia-dev/umbriel/blob/main/src/server/backend_manager.cpp): `src/server/backend_manager.cpp`
- [Xwayland support](https://github.com/noctalia-dev/umbriel/blob/main/src/xwayland/xwayland.cpp): `src/xwayland/xwayland.cpp`
- [Session lock](https://github.com/noctalia-dev/umbriel/blob/main/src/lock/session_lock.cpp): `src/lock/session_lock.cpp`

### Windows and workspaces

- [Workspace manager](https://github.com/noctalia-dev/umbriel/blob/main/src/workspace/workspace.cpp): `src/workspace/workspace.cpp`
- [Window views](https://github.com/noctalia-dev/umbriel/blob/main/src/view/view.h): `src/view/view.h`
- [Window layouts](https://github.com/noctalia-dev/umbriel/blob/main/src/layout/layout.h): `src/layout/layout.h`
- [Scratchpads](https://github.com/noctalia-dev/umbriel/blob/main/src/workspace/scratchpad.cpp): `src/workspace/scratchpad.cpp`

### Input and interaction

- [Pointer and cursor](https://github.com/noctalia-dev/umbriel/blob/main/src/input/cursor.cpp): `src/input/cursor.cpp`
- [Input seat](https://github.com/noctalia-dev/umbriel/blob/main/src/input/seat.h): `src/input/seat.h`
- [Workspace overview](https://github.com/noctalia-dev/umbriel/blob/main/src/overview/overview.cpp): `src/overview/overview.cpp`

### Display and effects

- [Output management](https://github.com/noctalia-dev/umbriel/blob/main/src/output/output.cpp): `src/output/output.cpp`
- [Effect registry](https://github.com/noctalia-dev/umbriel/blob/main/src/scene/effect_registry.cpp): `src/scene/effect_registry.cpp`
- [Scene renderer](https://github.com/noctalia-dev/umbriel/blob/main/umbrielfx/render/fx_renderer/fx_pass.c): `umbrielfx/render/fx_renderer/fx_pass.c`

### Configuration and control

- [Configuration](https://github.com/noctalia-dev/umbriel/blob/main/src/config/config.h): `src/config/config.h`
- [Config resolution](https://github.com/noctalia-dev/umbriel/blob/main/src/config/resolve.cpp): `src/config/resolve.cpp`
- [IPC commands](https://github.com/noctalia-dev/umbriel/blob/main/src/server/ipc_commands.cpp): `src/server/ipc_commands.cpp`
- [IPC client](https://github.com/noctalia-dev/umbriel/blob/main/src/cli/ipc_client.cpp): `src/cli/ipc_client.cpp`

### Other components

- **Desktop user**
- **Wayland clients**
- **wlroots**

## Connections

- Desktop user → CLI and startup: starts session
- CLI and startup → Compositor server: starts server (evidence: `src/main.cpp`)
- Compositor server → Backend manager: selects backend (evidence: `src/server/backend_manager.cpp`)
- Compositor server → Configuration: loads configuration (evidence: `src/server/server.cpp`)
- Compositor server → Config resolution: resolves settings (evidence: `src/server/server.cpp`)
- Wayland clients → Compositor server: connect
- Compositor server → wlroots: uses compositor APIs
- Compositor server → IPC commands: provides IPC
- Desktop user → IPC client: runs commands
- IPC client → IPC commands: sends commands (evidence: `src/cli/ipc_client.cpp`)
- Compositor server → Pointer and cursor: handles input (evidence: `src/server/server.cpp`)
- Pointer and cursor → Input seat: uses seat (evidence: `src/input/cursor.cpp`)
- Pointer and cursor → Workspace overview: routes interaction (evidence: `src/input/cursor.cpp`)
- Workspace manager → Window layouts: uses layouts (evidence: `src/workspace/workspace.cpp`)
- Workspace manager → Window views: manages windows (evidence: `src/workspace/workspace.cpp`)
- Workspace manager → Output management: associates outputs (evidence: `src/workspace/workspace.cpp`)
- Desktop user → Scratchpads: summons groups
- Compositor server → Session lock: supports locking (evidence: `src/lock/session_lock.cpp`)
- Compositor server → Xwayland support: supports X11 clients
- Output management → Effect registry: applies effects
- Effect registry → Scene renderer: selects scene effects
- Scene renderer → wlroots: extends scene rendering
