# lovefromhsd/hsdwl architecture

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

- Interactive diagram: https://gitdiagram.com/lovefromhsd/hsdwl
- Repository: https://github.com/lovefromhsd/hsdwl

## Overview

hsdwl is a Wayland compositor and desktop manager built on wlroots. Its principal workflow is accepting Wayland or X11 client surfaces, managing them as views in workspaces, and presenting those workspaces on outputs; users interact through keyboard and pointer input. Distinct desktop features include staged workspace organization, tab groups, overview, layer-shell surfaces, and window decoration/capture. The sampled code confirms server setup, view handling, pointer operations, stage rendering, and overview capture; some links to unsampled modules are therefore omitted.

Main entry points: [`src/stage.c`](https://github.com/lovefromhsd/hsdwl/blob/main/src/stage.c) (Stage manager), [`src/server.c`](https://github.com/lovefromhsd/hsdwl/blob/main/src/server.c) (Compositor server), [`src/view.c`](https://github.com/lovefromhsd/hsdwl/blob/main/src/view.c) (Window views), [`src/pointer.c`](https://github.com/lovefromhsd/hsdwl/blob/main/src/pointer.c) (Pointer handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Compositor runtime"]
  node_main["Process entry<br/>[main.c]"]
  node_server["Compositor server<br/>[server.c]"]
  node_config["Configuration<br/>[config.c]"]
end

subgraph group_clients["Client surfaces"]
  node_views["Window views<br/>[view.c]"]
  node_xwayland["XWayland support<br/>[xwayland.c]"]
  node_layer_shell["Layer surfaces<br/>[layer-shell.c]"]
  node_decorations["Window decoration<br/>[deco.c]"]
end

subgraph group_desktop["Workspace management"]
  node_workspaces["Workspace state<br/>[server.c]"]
  node_stage["Stage manager<br/>[stage.c]"]
  node_stage_sidebar["Stage sidebar<br/>[stage-sidebar.c]"]
  node_tab_groups["Tab groups<br/>[tab-group.c]"]
  node_tab_layout["Tab layout<br/>[tab-group-layout.c]"]
end

subgraph group_interaction["Interaction and effects"]
  node_pointer["Pointer handling<br/>[pointer.c]"]
  node_input["Input handling<br/>[input.c]"]
  node_seat["Wayland seat<br/>[seat.c]"]
  node_overview["Workspace overview<br/>[expo.c]"]
  node_animations["Animations<br/>[animation.c]"]
  node_capture["View capture<br/>[view-capture.c]"]
end

subgraph group_display["Display and shell"]
  node_outputs["Output management"]
  node_output["Output rendering<br/>[output.c]"]
  node_wallpaper["Wallpaper<br/>[wallpaper.c]"]
end

node_user(("Desktop user"))
node_wayland_clients(("Wayland clients"))
node_x_clients(("X11 clients"))
node_input_devices(("Input devices"))

node_main -->|"starts"| node_server
node_server -->|"loads"| node_config
node_server -->|"initializes"| node_seat
node_server -->|"loads"| node_wallpaper
node_wayland_clients -->|"provide surfaces"| node_views
node_x_clients -->|"connect through"| node_xwayland
node_xwayland -->|"creates views"| node_views
node_wayland_clients -->|"request surfaces"| node_layer_shell
node_views -->|"occupy"| node_workspaces
node_views -->|"display with"| node_decorations
node_user -->|"operates"| node_input_devices
node_input_devices -->|"deliver events"| node_input
node_input -->|"dispatches pointer"| node_pointer
node_input -->|"dispatches input"| node_seat
node_pointer -->|"moves and focuses"| node_views
node_pointer -->|"manipulates"| node_tab_groups
node_pointer -->|"controls"| node_overview
node_stage -->|"renders"| node_stage_sidebar
node_stage -->|"organizes"| node_workspaces
node_stage -->|"manages"| node_tab_groups
node_tab_groups -->|"updates layout"| node_tab_layout
node_overview -->|"captures desktops"| node_workspaces
node_overview -->|"uses captures"| node_capture
node_stage -->|"captures views"| node_capture
node_stage -->|"animates transitions"| node_animations
node_tab_groups -->|"animates changes"| node_animations
node_server -->|"configures"| node_output
node_outputs -->|"manages"| node_output

click node_main "https://github.com/lovefromhsd/hsdwl/blob/main/src/main.c"
click node_server "https://github.com/lovefromhsd/hsdwl/blob/main/src/server.c"
click node_config "https://github.com/lovefromhsd/hsdwl/blob/main/src/config.c"
click node_views "https://github.com/lovefromhsd/hsdwl/blob/main/src/view.c"
click node_xwayland "https://github.com/lovefromhsd/hsdwl/blob/main/src/xwayland.c"
click node_layer_shell "https://github.com/lovefromhsd/hsdwl/blob/main/src/layer-shell.c"
click node_decorations "https://github.com/lovefromhsd/hsdwl/blob/main/src/deco.c"
click node_workspaces "https://github.com/lovefromhsd/hsdwl/blob/main/src/server.c"
click node_stage "https://github.com/lovefromhsd/hsdwl/blob/main/src/stage.c"
click node_stage_sidebar "https://github.com/lovefromhsd/hsdwl/blob/main/src/stage-sidebar.c"
click node_tab_groups "https://github.com/lovefromhsd/hsdwl/blob/main/src/tab-group.c"
click node_tab_layout "https://github.com/lovefromhsd/hsdwl/blob/main/src/tab-group-layout.c"
click node_pointer "https://github.com/lovefromhsd/hsdwl/blob/main/src/pointer.c"
click node_input "https://github.com/lovefromhsd/hsdwl/blob/main/src/input.c"
click node_seat "https://github.com/lovefromhsd/hsdwl/blob/main/src/seat.c"
click node_overview "https://github.com/lovefromhsd/hsdwl/blob/main/src/expo.c"
click node_animations "https://github.com/lovefromhsd/hsdwl/blob/main/src/animation.c"
click node_capture "https://github.com/lovefromhsd/hsdwl/blob/main/src/view-capture.c"
click node_outputs "https://github.com/lovefromhsd/hsdwl/blob/main/src/output-management.c"
click node_output "https://github.com/lovefromhsd/hsdwl/blob/main/src/output.c"
click node_wallpaper "https://github.com/lovefromhsd/hsdwl/blob/main/src/wallpaper.c"

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_config,node_user,node_wayland_clients,node_x_clients toneBlue
class node_views,node_xwayland,node_layer_shell,node_decorations toneAmber
class node_workspaces,node_stage,node_stage_sidebar,node_tab_groups,node_tab_layout toneMint
class node_pointer,node_input,node_seat,node_overview,node_animations,node_capture toneRose
class node_outputs,node_output,node_wallpaper,node_input_devices toneIndigo
```

## Components

### Compositor runtime

- [Process entry](https://github.com/lovefromhsd/hsdwl/blob/main/src/main.c): `src/main.c`
- [Compositor server](https://github.com/lovefromhsd/hsdwl/blob/main/src/server.c): `src/server.c`
- [Configuration](https://github.com/lovefromhsd/hsdwl/blob/main/src/config.c): `src/config.c`

### Client surfaces

- [Window views](https://github.com/lovefromhsd/hsdwl/blob/main/src/view.c): `src/view.c`
- [XWayland support](https://github.com/lovefromhsd/hsdwl/blob/main/src/xwayland.c): `src/xwayland.c`
- [Layer surfaces](https://github.com/lovefromhsd/hsdwl/blob/main/src/layer-shell.c): `src/layer-shell.c`
- [Window decoration](https://github.com/lovefromhsd/hsdwl/blob/main/src/deco.c): `src/deco.c`

### Workspace management

- [Workspace state](https://github.com/lovefromhsd/hsdwl/blob/main/src/server.c): `src/server.c`
- [Stage manager](https://github.com/lovefromhsd/hsdwl/blob/main/src/stage.c): `src/stage.c`
- [Stage sidebar](https://github.com/lovefromhsd/hsdwl/blob/main/src/stage-sidebar.c): `src/stage-sidebar.c`
- [Tab groups](https://github.com/lovefromhsd/hsdwl/blob/main/src/tab-group.c): `src/tab-group.c`
- [Tab layout](https://github.com/lovefromhsd/hsdwl/blob/main/src/tab-group-layout.c): `src/tab-group-layout.c`

### Interaction and effects

- [Pointer handling](https://github.com/lovefromhsd/hsdwl/blob/main/src/pointer.c): `src/pointer.c`
- [Input handling](https://github.com/lovefromhsd/hsdwl/blob/main/src/input.c): `src/input.c`
- [Wayland seat](https://github.com/lovefromhsd/hsdwl/blob/main/src/seat.c): `src/seat.c`
- [Workspace overview](https://github.com/lovefromhsd/hsdwl/blob/main/src/expo.c): `src/expo.c`
- [Animations](https://github.com/lovefromhsd/hsdwl/blob/main/src/animation.c): `src/animation.c`
- [View capture](https://github.com/lovefromhsd/hsdwl/blob/main/src/view-capture.c): `src/view-capture.c`

### Display and shell

- [Output management](https://github.com/lovefromhsd/hsdwl/blob/main/src/output-management.c): `src/output-management.c`
- [Output rendering](https://github.com/lovefromhsd/hsdwl/blob/main/src/output.c): `src/output.c`
- [Wallpaper](https://github.com/lovefromhsd/hsdwl/blob/main/src/wallpaper.c): `src/wallpaper.c`

### Other components

- **Desktop user**
- **Wayland clients**
- **X11 clients**
- **Input devices**

## Connections

- Process entry → Compositor server: starts
- Compositor server → Configuration: loads
- Compositor server → Wayland seat: initializes
- Compositor server → Wallpaper: loads
- Wayland clients → Window views: provide surfaces
- X11 clients → XWayland support: connect through
- XWayland support → Window views: creates views
- Wayland clients → Layer surfaces: request surfaces
- Window views → Workspace state: occupy
- Window views → Window decoration: display with
- Desktop user → Input devices: operates
- Input devices → Input handling: deliver events
- Input handling → Pointer handling: dispatches pointer
- Input handling → Wayland seat: dispatches input
- Pointer handling → Window views: moves and focuses
- Pointer handling → Tab groups: manipulates
- Pointer handling → Workspace overview: controls
- Stage manager → Stage sidebar: renders
- Stage manager → Workspace state: organizes
- Stage manager → Tab groups: manages
- Tab groups → Tab layout: updates layout
- Workspace overview → Workspace state: captures desktops
- Workspace overview → View capture: uses captures
- Stage manager → View capture: captures views
- Stage manager → Animations: animates transitions
- Tab groups → Animations: animates changes
- Compositor server → Output rendering: configures
- Output management → Output rendering: manages