# vodkanull/pudu architecture

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

- Interactive diagram: https://gitdiagram.com/vodkanull/pudu
- Repository: https://github.com/vodkanull/pudu

## Overview

1. **What this repository is**
   - `pudu` is a **single-process Wayland compositor** built on **wlroots**.
   - Architecturally, it sits at the boundary between **Wayland clients** and the **Linux input/output stack**, acting as both display server and window manager.

2. **Top-level structure**
   - The repo is small and centered around `src/`.
   - `src/pudu.c` is the main compositor implementation.
   - `src/pudu.h` is the shared header for the compositor’s internal types and declarations.
   - `src/Makefile` drives compilation.
   - `src/pudu.desktop` packages it as a Wayland session for a display manager.
   - `src/config` is the example/user config template.

3. **Core runtime architecture**
   - The compositor starts from `pudu`, creates the Wayland server state, initializes wlroots backend components, and then enters the event loop.
   - At runtime it mediates:
     - **input events** from keyboard/mouse/touch via libinput/wlroots,
     - **surface events** from Wayland clients,
     - **rendering/output updates** through wlroots’ output/backend abstraction.

4. **Main dependency stack**
   - The README makes the dependency boundary explicit: **wlroots 0.19**, **Wayland**, **libxkbcommon**, **libinput**, **cairo**, **seatd**, and a terminal app such as **kitty**.
   - This indicates `pudu` is not a self-contained graphics stack; it relies on wlroots for most platform integration and protocol plumbing.

5. **Wayland protocol boundary**
   - `src/protocols/` contains protocol XMLs used by the compositor.
   - Standard protocols include:
     - `xdg-shell.xml` for normal application windows,
     - `wlr-layer-shell-unstable-v1.xml` for panels/overlays,
     - `pointer-constraints-unstable-v1.xml` for pointer confinement/locking.
   - Custom extension protocols include:
     - `ext-session-lock-v1.xml` for lock-screen/session-lock behavior,
     - `ext-workspace-v1.xml` for workspace awareness.
   - These XML files define the compositor’s external API surface and are important for diagramming client interaction points.

6. **Window management model**
   - The README describes it as a **minimal tiling compositor**.
   - That suggests the core logic in `pudu.c` manages:
     - mapping new `xdg-shell` surfaces,
     - arranging windows into tiling layout,
     - handling focus and surface lifecycle,
     - supporting manual movement/closing via compositor shortcuts.
   - User interaction is centered on simple keyboard/mouse bindings rather than a separate window-manager process.

7. **Input and session control**
   - Input flows from the seat/input layer into compositor actions:
     - **Super + Left Click drag** moves windows,
     - **Super + C** closes the focused window,
     - **Super + Enter** launches the configured terminal.
   - The need for `seatd` and the note about adding the user to `input,seat` show that direct TTY/session ownership is part of the runtime boundary.

8. **Configuration path**
   - Configuration lives at `~/.config/pudu/config`.
   - The example config in `src/config` indicates runtime behavior is customizable without recompiling.
   - The config likely controls keybindings and default terminal command, making it a small but important control plane separate from compositor code.

9. **Build and packaging flow**
   - The build is local and source-based: clone repo → `cd src` → `make`.
   - The output binary is copied into `/usr/local/bin/`.
   - `pudu.desktop` is installed into `/usr/share/wayland-sessions/` so a display manager can launch it as a session.
   - This means packaging is intentionally lightweight and distro integration is manual.

10. **External behavior and project constraints**
   - The README explicitly says **XWayland is not supported**, so the architecture is **pure Wayland only**.
   - That is a meaningful boundary: legacy X11 clients are excluded from the supported client set.
   - The project is also tested only on **Arch Linux**, which matters for the deployment/runtime assumptions around dependencies and seat management.

11. **How to draw the architecture**
   - A useful diagram would show:
     - **Wayland clients** on one side,
     - **pudu compositor** in the center,
     - **wlroots + system libraries** beneath it,
     - **seatd / kernel input-output stack** below that,
     - and **config file + protocol XMLs** as supporting inputs to the compositor build/runtime behavior.
   - The compositor itself appears to be a **single monolithic core**, not a multi-service architecture.

12. **Overall repo shape**
   - This repository is intentionally compact: one core compositor, a small set of protocol definitions, one example config, and install metadata.
   - The key architecture question is not service decomposition, but rather **which Wayland protocols and wlroots subsystems `pudu` enables and how it manages windows, focus, and input inside one event-driven process**.

Main entry points: [`src/pudu.c`](https://github.com/vodkanull/pudu/blob/main/src/pudu.c) (pudu), [`src/protocols`](https://github.com/vodkanull/pudu/tree/main/src/protocols) (protocols), [`src/protocols/xdg-shell.xml`](https://github.com/vodkanull/pudu/blob/main/src/protocols/xdg-shell.xml) (xdg-shell), [`src/protocols/wlr-layer-shell-unstable-v1.xml`](https://github.com/vodkanull/pudu/blob/main/src/protocols/wlr-layer-shell-unstable-v1.xml) (layer-shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
end

subgraph group_core["Core compositor"]
  node_pudu_core["pudu<br/>compositor core<br/>[pudu.c]"]
  node_pudu_api["pudu.h<br/>internal API<br/>[pudu.h]"]
end

subgraph group_protocols["Protocols"]
  node_protocol_dir["protocols<br/>protocol bundle"]
  node_xdg_shell["xdg-shell<br/>wayland protocol<br/>[xdg-shell.xml]"]
  node_layer_shell["layer-shell<br/>wayland protocol"]
  node_pointer_constraints["pointer constraints<br/>wayland protocol"]
  node_session_lock["session lock<br/>custom protocol"]
  node_workspace["workspace<br/>custom protocol"]
end

subgraph group_support["Support"]
  node_config["config"]
  node_makefile["Makefile<br/>build script"]
  node_desktop["session entry<br/>desktop session<br/>[pudu.desktop]"]
end

subgraph group_runtime["Runtime stack"]
  node_wayland(("Wayland<br/>client/server protocol"))
  node_wlroots["wlroots<br/>compositor framework"]
  node_input_stack["input stack<br/>libinput/xkbcommon"]
  node_seatd_kernel["seatd / kernel<br/>system io"]
  node_display_manager["display manager<br/>session launcher"]
  node_terminal_app["terminal<br/>client app"]
end

node_wayland -->|"client surfaces"| node_pudu_core
node_pudu_core -->|"serve protocol"| node_wayland
node_pudu_core -->|"uses backend"| node_wlroots
node_wlroots -->|"input events"| node_input_stack
node_input_stack -->|"device access"| node_seatd_kernel
node_pudu_core -->|"shared state"| node_pudu_api
node_config -->|"runtime settings"| node_pudu_core
node_makefile -->|"builds"| node_pudu_core
node_desktop -->|"session launch"| node_display_manager
node_display_manager -->|"starts session"| node_pudu_core
node_protocol_dir -->|"contains"| node_xdg_shell
node_protocol_dir -->|"contains"| node_layer_shell
node_protocol_dir -->|"contains"| node_pointer_constraints
node_protocol_dir -->|"contains"| node_session_lock
node_protocol_dir -->|"contains"| node_workspace
node_xdg_shell -->|"window mapping"| node_pudu_core
node_layer_shell -->|"overlays"| node_pudu_core
node_pointer_constraints -->|"pointer lock"| node_pudu_core
node_session_lock -->|"lockscreen"| node_pudu_core
node_workspace -->|"workspace state"| node_pudu_core
node_pudu_core -->|"launches"| node_terminal_app

click node_pudu_core "https://github.com/vodkanull/pudu/blob/main/src/pudu.c"
click node_pudu_api "https://github.com/vodkanull/pudu/blob/main/src/pudu.h"
click node_config "https://github.com/vodkanull/pudu/tree/main/src/config"
click node_makefile "https://github.com/vodkanull/pudu/tree/main/src/Makefile"
click node_desktop "https://github.com/vodkanull/pudu/blob/main/src/pudu.desktop"
click node_protocol_dir "https://github.com/vodkanull/pudu/tree/main/src/protocols"
click node_xdg_shell "https://github.com/vodkanull/pudu/blob/main/src/protocols/xdg-shell.xml"
click node_layer_shell "https://github.com/vodkanull/pudu/blob/main/src/protocols/wlr-layer-shell-unstable-v1.xml"
click node_pointer_constraints "https://github.com/vodkanull/pudu/blob/main/src/protocols/pointer-constraints-unstable-v1.xml"
click node_session_lock "https://github.com/vodkanull/pudu/blob/main/src/protocols/ext-session-lock-v1.xml"
click node_workspace "https://github.com/vodkanull/pudu/blob/main/src/protocols/ext-workspace-v1.xml"

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_pudu_core,node_pudu_api toneAmber
class node_protocol_dir,node_xdg_shell,node_layer_shell,node_pointer_constraints,node_session_lock,node_workspace toneMint
class node_config,node_makefile,node_desktop toneRose
class node_wayland,node_wlroots,node_input_stack,node_seatd_kernel,node_display_manager,node_terminal_app toneIndigo
```

## Components

### Core compositor

Main event-driven compositor process and shared internal API.

- [pudu](https://github.com/vodkanull/pudu/blob/main/src/pudu.c): compositor core · Single-process Wayland compositor and tiling/window-management runtime. · `src/pudu.c`
- [pudu.h](https://github.com/vodkanull/pudu/blob/main/src/pudu.h): internal API · Shared compositor types, declarations, and cross-module state. · `src/pudu.h`

### Protocols

Wayland protocol XMLs that define the compositor's client-facing surface.

- [protocols](https://github.com/vodkanull/pudu/tree/main/src/protocols): protocol bundle · Repository-local Wayland protocol definitions consumed by the compositor. · `src/protocols`
- [xdg-shell](https://github.com/vodkanull/pudu/blob/main/src/protocols/xdg-shell.xml): wayland protocol · Standard shell protocol for normal application windows. · `src/protocols/xdg-shell.xml`
- [layer-shell](https://github.com/vodkanull/pudu/blob/main/src/protocols/wlr-layer-shell-unstable-v1.xml): wayland protocol · Protocol for panels, overlays, and other non-toplevel surfaces. · `src/protocols/wlr-layer-shell-unstable-v1.xml`
- [pointer constraints](https://github.com/vodkanull/pudu/blob/main/src/protocols/pointer-constraints-unstable-v1.xml): wayland protocol · Pointer confinement and locking for focused client interactions. · `src/protocols/pointer-constraints-unstable-v1.xml`
- [session lock](https://github.com/vodkanull/pudu/blob/main/src/protocols/ext-session-lock-v1.xml): custom protocol · Compositor extension for lock-screen and session-lock behavior. · `src/protocols/ext-session-lock-v1.xml`
- [workspace](https://github.com/vodkanull/pudu/blob/main/src/protocols/ext-workspace-v1.xml): custom protocol · Compositor extension for workspace awareness and coordination. · `src/protocols/ext-workspace-v1.xml`

### Support

Build, configuration, and session entry points.

- [config](https://github.com/vodkanull/pudu/tree/main/src/config): example config · User-facing configuration template for bindings and defaults. · `src/config`
- [Makefile](https://github.com/vodkanull/pudu/tree/main/src/Makefile): build script · Build entry point for compiling the compositor from source. · `src/Makefile`
- [session entry](https://github.com/vodkanull/pudu/blob/main/src/pudu.desktop): desktop session · Wayland session metadata for display manager launch. · `src/pudu.desktop`

### Runtime stack

External libraries and system services the compositor sits on top of.

- **Wayland**: client/server protocol · Base protocol boundary between clients and compositor.
- **wlroots**: compositor framework · Backend, rendering, and protocol plumbing used by the compositor.
- **input stack**: libinput/xkbcommon · Keyboard, pointer, touch, and keymap handling via system libraries.
- **seatd / kernel**: system io · Session ownership and low-level input/output access through the OS stack.
- **display manager**: session launcher · External launcher that starts Pudu as a Wayland session.
- **terminal**: client app · Configured default terminal launched by compositor shortcuts.

## Connections

- Wayland → pudu: client surfaces · Wayland clients connect and present surfaces to the compositor.
- pudu → Wayland: serve protocol · The compositor exposes the Wayland server boundary back to clients.
- pudu → wlroots: uses backend · Pudu delegates rendering, outputs, and protocol plumbing to wlroots.
- wlroots → input stack: input events · wlroots routes keyboard and pointer events from libinput and related stacks.
- input stack → seatd / kernel: device access · Low-level input and session ownership come from seatd and the kernel.
- pudu → pudu.h: shared state · Core implementation uses the internal declarations and shared types.
- config → pudu: runtime settings · Configuration influences bindings, defaults, and compositor behavior.
- Makefile → pudu: builds · Source build compiles the compositor implementation.
- session entry → display manager: session launch · Desktop entry registers the compositor as a selectable session.
- display manager → pudu: starts session · Display manager can launch Pudu as the active Wayland session.
- protocols → xdg-shell: contains · Protocol bundle includes standard shell definitions.
- protocols → layer-shell: contains · Protocol bundle includes layer-shell definitions.
- protocols → pointer constraints: contains · Protocol bundle includes pointer confinement and lock definitions.
- protocols → session lock: contains · Protocol bundle includes session lock extension definitions.
- protocols → workspace: contains · Protocol bundle includes workspace extension definitions.
- xdg-shell → pudu: window mapping · Normal application windows are managed through xdg-shell.
- layer-shell → pudu: overlays · Panels and overlays are handled through layer-shell surfaces.
- pointer constraints → pudu: pointer lock · The compositor honors confinement and locking requests.
- session lock → pudu: lockscreen · Lock-screen flow is mediated through the session-lock extension.
- workspace → pudu: workspace state · Workspace awareness feeds compositor layout and focus decisions.
- pudu → terminal: launches · Keyboard shortcuts can spawn the configured terminal.