# riverwm/river architecture

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

- Interactive diagram: https://gitdiagram.com/riverwm/river
- Repository: https://github.com/riverwm/river

## Overview

River is a Wayland compositor that deliberately delegates window-management policy to a separate process. Its principal workflow is: start the compositor, accept Wayland clients and a compatible window manager, then mediate window-management protocol events while providing rendering, input, shell surfaces, and optional Xwayland support. The README documents these capabilities; source excerpts were limited to logging and C headers, so detailed internal call wiring is not asserted.

Main entry points: [`river/Server.zig`](https://github.com/riverwm/river/blob/main/river/Server.zig) (Compositor server), [`river/WindowManager.zig`](https://github.com/riverwm/river/blob/main/river/WindowManager.zig) (Window manager interface), [`river/Seat.zig`](https://github.com/riverwm/river/blob/main/river/Seat.zig) (Input seat), [`river/main.zig`](https://github.com/riverwm/river/blob/main/river/main.zig) (River entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_river_main["River entry point<br/>[main.zig]"]
  node_server["Compositor server<br/>[Server.zig]"]
end

subgraph group_wm["Window management"]
  node_wm_protocol["Window-management protocol"]
  node_window_manager["Window manager interface<br/>[WindowManager.zig]"]
  node_window["Window surfaces<br/>[Window.zig]"]
  node_wm_node["Management nodes<br/>[WmNode.zig]"]
end

subgraph group_render_input["Rendering and input"]
  node_output_manager["Output management<br/>[OutputManager.zig]"]
  node_output["Display output<br/>[Output.zig]"]
  node_scene["Scene rendering<br/>[Scene.zig]"]
  node_input_manager["Input management<br/>[InputManager.zig]"]
  node_seat["Input seat<br/>[Seat.zig]"]
  node_keyboard["Keyboard input<br/>[Keyboard.zig]"]
  node_cursor["Pointer and cursor<br/>[Cursor.zig]"]
end

subgraph group_extensions["Protocol extensions"]
  node_layer_shell["Layer shell<br/>[LayerShell.zig]"]
  node_xkb["XKB configuration<br/>[XkbConfig.zig]"]
  node_xkb_bindings["XKB bindings<br/>[XkbBindings.zig]"]
end

subgraph group_xwayland["Xwayland"]
  node_xwayland["Xwayland windows<br/>[XwaylandWindow.zig]"]
end

node_user(("User"))
node_clients(("Wayland clients"))
node_wm_process(("Window manager"))

node_user -->|"starts"| node_river_main
node_river_main -->|"initializes"| node_server
node_clients -->|"connect to"| node_server
node_wm_process -->|"connects through"| node_window_manager
node_window_manager -->|"implements"| node_wm_protocol
node_server -->|"mediates"| node_window_manager
node_server -->|"manages surfaces"| node_window
node_window_manager -->|"manages nodes"| node_wm_node
node_server -->|"provides outputs"| node_output_manager
node_output_manager -->|"manages"| node_output
node_server -->|"renders scene"| node_scene
node_server -->|"handles input"| node_input_manager
node_input_manager -->|"coordinates devices"| node_seat
node_seat -->|"dispatches input"| node_keyboard
node_seat -->|"dispatches pointer"| node_cursor
node_server -->|"supports shell surfaces"| node_layer_shell
node_server -->|"supports configuration"| node_xkb
node_server -->|"supports bindings"| node_xkb_bindings
node_clients -.->|"use X11 via"| node_xwayland
node_server -.->|"supports"| node_xwayland

click node_river_main "https://github.com/riverwm/river/blob/main/river/main.zig"
click node_server "https://github.com/riverwm/river/blob/main/river/Server.zig"
click node_wm_protocol "https://github.com/riverwm/river/blob/main/protocol/river-window-management-v1.xml"
click node_window_manager "https://github.com/riverwm/river/blob/main/river/WindowManager.zig"
click node_window "https://github.com/riverwm/river/blob/main/river/Window.zig"
click node_wm_node "https://github.com/riverwm/river/blob/main/river/WmNode.zig"
click node_output_manager "https://github.com/riverwm/river/blob/main/river/OutputManager.zig"
click node_output "https://github.com/riverwm/river/blob/main/river/Output.zig"
click node_scene "https://github.com/riverwm/river/blob/main/river/Scene.zig"
click node_input_manager "https://github.com/riverwm/river/blob/main/river/InputManager.zig"
click node_seat "https://github.com/riverwm/river/blob/main/river/Seat.zig"
click node_keyboard "https://github.com/riverwm/river/blob/main/river/Keyboard.zig"
click node_cursor "https://github.com/riverwm/river/blob/main/river/Cursor.zig"
click node_layer_shell "https://github.com/riverwm/river/blob/main/river/LayerShell.zig"
click node_xkb "https://github.com/riverwm/river/blob/main/river/XkbConfig.zig"
click node_xkb_bindings "https://github.com/riverwm/river/blob/main/river/XkbBindings.zig"
click node_xwayland "https://github.com/riverwm/river/blob/main/river/XwaylandWindow.zig"

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_river_main,node_server,node_user,node_clients toneBlue
class node_wm_protocol,node_window_manager,node_window,node_wm_node toneAmber
class node_output_manager,node_output,node_scene,node_input_manager,node_seat,node_keyboard,node_cursor toneMint
class node_layer_shell,node_xkb,node_xkb_bindings toneRose
class node_xwayland,node_wm_process toneIndigo
```

## Components

### Runtime

- [River entry point](https://github.com/riverwm/river/blob/main/river/main.zig): `river/main.zig`
- [Compositor server](https://github.com/riverwm/river/blob/main/river/Server.zig): `river/Server.zig`

### Window management

- [Window-management protocol](https://github.com/riverwm/river/blob/main/protocol/river-window-management-v1.xml): `protocol/river-window-management-v1.xml`
- [Window manager interface](https://github.com/riverwm/river/blob/main/river/WindowManager.zig): `river/WindowManager.zig`
- [Window surfaces](https://github.com/riverwm/river/blob/main/river/Window.zig): `river/Window.zig`
- [Management nodes](https://github.com/riverwm/river/blob/main/river/WmNode.zig): `river/WmNode.zig`

### Rendering and input

- [Output management](https://github.com/riverwm/river/blob/main/river/OutputManager.zig): `river/OutputManager.zig`
- [Display output](https://github.com/riverwm/river/blob/main/river/Output.zig): `river/Output.zig`
- [Scene rendering](https://github.com/riverwm/river/blob/main/river/Scene.zig): `river/Scene.zig`
- [Input management](https://github.com/riverwm/river/blob/main/river/InputManager.zig): `river/InputManager.zig`
- [Input seat](https://github.com/riverwm/river/blob/main/river/Seat.zig): `river/Seat.zig`
- [Keyboard input](https://github.com/riverwm/river/blob/main/river/Keyboard.zig): `river/Keyboard.zig`
- [Pointer and cursor](https://github.com/riverwm/river/blob/main/river/Cursor.zig): `river/Cursor.zig`

### Protocol extensions

- [Layer shell](https://github.com/riverwm/river/blob/main/river/LayerShell.zig): `river/LayerShell.zig`
- [XKB configuration](https://github.com/riverwm/river/blob/main/river/XkbConfig.zig): `river/XkbConfig.zig`
- [XKB bindings](https://github.com/riverwm/river/blob/main/river/XkbBindings.zig): `river/XkbBindings.zig`

### Xwayland

- [Xwayland windows](https://github.com/riverwm/river/blob/main/river/XwaylandWindow.zig): `river/XwaylandWindow.zig`

### Other components

- **User**
- **Wayland clients**
- **Window manager**

## Connections

- User → River entry point: starts
- River entry point → Compositor server: initializes
- Wayland clients → Compositor server: connect to
- Window manager → Window manager interface: connects through
- Window manager interface → Window-management protocol: implements
- Compositor server → Window manager interface: mediates
- Compositor server → Window surfaces: manages surfaces
- Window manager interface → Management nodes: manages nodes
- Compositor server → Output management: provides outputs
- Output management → Display output: manages
- Compositor server → Scene rendering: renders scene
- Compositor server → Input management: handles input
- Input management → Input seat: coordinates devices
- Input seat → Keyboard input: dispatches input
- Input seat → Pointer and cursor: dispatches pointer
- Compositor server → Layer shell: supports shell surfaces
- Compositor server → XKB configuration: supports configuration
- Compositor server → XKB bindings: supports bindings
- Wayland clients → Xwayland windows: use X11 via
- Compositor server → Xwayland windows: supports
