# swaywm/sway architecture

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

- Interactive diagram: https://gitdiagram.com/swaywm/sway
- Repository: https://github.com/swaywm/sway

## Overview

#### Purpose and binaries
Sway is a C, i3-compatible Wayland compositor built with Meson/Ninja. The primary compositor executable starts at `sway/main.c`; companion processes are the status bar (`swaybar/main.c`), IPC CLI (`swaymsg/main.c`), and warning/error UI (`swaynag/main.c`). Top-level build composition is in `meson.build`.

#### Server and Wayland boundary
`sw​​ay/server.c` initializes and owns compositor-facing state, delegating protocol, rendering, output, and surface primitives to wlroots. Desktop protocol integration is separated in `sway/desktop/xdg_shell.c`, `sway/desktop/layer_shell.c`, and `sway/desktop/xwayland.c`, forming the boundary between Wayland/Xwayland clients and Sway’s internal window model.

#### Configuration and command execution
At startup or reload, `sway/config.c` parses i3-compatible configuration and creates persistent policy/state for inputs, outputs, seats, bars, bindings, and rules. `sway/commands.c` dispatches config and runtime commands into focused implementations under `sway/commands/`; criteria matching in `sway/criteria.c` selects target views/containers. Commands mutate compositor state rather than directly rendering.

#### Window tree, layout, and transactions
The canonical desktop model is the root/output/workspace/container/view tree under `sway/tree/root.c`, `sway/tree/container.c`, and `sway/tree/view.c`. Arrangement in `sway/tree/arrange.c` turns tiling/floating layout state into geometry. `sway/desktop/transaction.c` coordinates state transitions with clients, separating requested layout changes from committed visual state.

#### Input and interaction state machines
Input device discovery and lifecycle flow through `sway/input/input-manager.c` and `sway/input/libinput.c`. Seats, keyboards, cursors, touch/tablet, focus, and pointer-driven move/resize operations are mediated by `sway/input/seat.c`, `sway/input/cursor.c`, and specialized `seatop_*` modules. This layer maps wlroots/libinput events into tree focus and layout actions.

#### IPC and external control
The compositor publishes i3-compatible IPC through `sway/ipc-server.c`; `sway/ipc-json.c` serializes tree, workspace, input, output, and event data using json-c. Consumers use the reusable client transport in `common/ipc-client.c`, notably `swaymsg/main.c` and `swaybar/ipc.c`. IPC is the principal process boundary for automation and bar updates.

#### Bar, notifications, and shared rendering
`swaybar/bar.c` manages bar instances configured by Sway, consumes compositor IPC, and renders workspace/status/tray UI through `swaybar/render.c`; i3bar status input is handled in `swaybar/i3bar.c`. `swaynag/swaynag.c` is an independent Wayland notification/error surface. Shared Cairo/Pango drawing and Wayland buffer utilities live in `common/cairo.c`, `common/pango.c`, and `client/pool-buffer.c`.

#### Runtime dependencies and protocols
The system runs on Wayland and wlroots, with optional Xwayland support; libinput drives physical input. Cairo/Pango provide text and rendering, PCRE2 supports criteria, and json-c supports IPC. Local protocol definitions, including layer-shell and output power management, are in `protocols/wlr-layer-shell-unstable-v1.xml` and `protocols/wlr-output-power-management-unstable-v1.xml`.

Main entry points: [`meson.build`](https://github.com/swaywm/sway/blob/master/meson.build) (Meson/Ninja build), [`sway/commands.c`](https://github.com/swaywm/sway/blob/master/sway/commands.c) (Command dispatcher), [`sway/tree/root.c`](https://github.com/swaywm/sway/blob/master/sway/tree/root.c) (Desktop tree), [`sway/main.c`](https://github.com/swaywm/sway/blob/master/sway/main.c) (sway compositor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Compositor Core"]
  node_sway["sway compositor<br/>executable<br/>[main.c]"]
  node_server["Server lifecycle<br/>compositor state<br/>[server.c]"]
  node_config["Config policy<br/>configuration<br/>[config.c]"]
  node_commands["Command dispatcher<br/>command engine<br/>[commands.c]"]
  node_criteria["Criteria matcher<br/>target selection<br/>[criteria.c]"]
  node_tree["Desktop tree<br/>window model<br/>[root.c]"]
  node_arrange["Layout arrangement<br/>layout engine<br/>[arrange.c]"]
  node_transactions["Desktop transactions<br/>state synchronization<br/>[transaction.c]"]
  node_desktop["Client protocol integration<br/>desktop protocols<br/>[xdg_shell.c]"]
  node_wlroots{{"wlroots / Wayland<br/>runtime boundary"}}
end

subgraph group_input["Input"]
  node_input_manager["Input manager<br/>device lifecycle<br/>[input-manager.c]"]
  node_seat["Seats and interactions<br/>focus and pointer state<br/>[seat.c]"]
end

subgraph group_ipc["IPC"]
  node_ipc_server["IPC server<br/>IPC endpoint<br/>[ipc-server.c]"]
  node_ipc_json["IPC JSON<br/>serialization<br/>[ipc-json.c]"]
  node_ipc_client["IPC client transport<br/>shared transport<br/>[ipc-client.c]"]
end

subgraph group_clients["Companion Clients"]
  node_swaymsg["swaymsg<br/>CLI executable<br/>[main.c]"]
  node_swaybar["swaybar<br/>bar process<br/>[bar.c]"]
  node_swaynag["swaynag<br/>Wayland UI process<br/>[swaynag.c]"]
  node_drawing["Shared drawing and buffers<br/>rendering utilities<br/>[cairo.c]"]
end

node_build{{"Meson/Ninja build<br/>build system<br/>[meson.build]"}}

node_build -->|"builds"| node_sway
node_build -->|"builds"| node_swaymsg
node_build -->|"builds"| node_swaybar
node_build -->|"builds"| node_swaynag
node_sway -->|"initializes"| node_server
node_sway -->|"loads and reloads"| node_config
node_server -->|"uses"| node_wlroots
node_desktop -->|"bridges clients through"| node_wlroots
node_config -->|"defines commands for"| node_commands
node_commands -->|"selects targets via"| node_criteria
node_commands -->|"mutates"| node_tree
node_tree -->|"provides layout state"| node_arrange
node_arrange -->|"requests geometry changes"| node_transactions
node_transactions -->|"synchronizes clients"| node_desktop
node_input_manager -->|"routes device events"| node_seat
node_seat -->|"updates focus and actions"| node_tree
node_input_manager -->|"uses input events"| node_wlroots
node_ipc_server -->|"executes runtime commands"| node_commands
node_ipc_server -->|"serializes through"| node_ipc_json
node_ipc_json -->|"queries state from"| node_tree
node_swaymsg -->|"uses"| node_ipc_client
node_swaybar -->|"uses"| node_ipc_client
node_ipc_client -->|"connects to"| node_ipc_server
node_swaybar -->|"renders with"| node_drawing
node_swaynag -->|"renders with"| node_drawing
node_swaynag -->|"creates Wayland surface through"| node_wlroots

click node_build "https://github.com/swaywm/sway/blob/master/meson.build"
click node_sway "https://github.com/swaywm/sway/blob/master/sway/main.c"
click node_server "https://github.com/swaywm/sway/blob/master/sway/server.c"
click node_config "https://github.com/swaywm/sway/blob/master/sway/config.c"
click node_commands "https://github.com/swaywm/sway/blob/master/sway/commands.c"
click node_criteria "https://github.com/swaywm/sway/blob/master/sway/criteria.c"
click node_tree "https://github.com/swaywm/sway/blob/master/sway/tree/root.c"
click node_arrange "https://github.com/swaywm/sway/blob/master/sway/tree/arrange.c"
click node_transactions "https://github.com/swaywm/sway/blob/master/sway/desktop/transaction.c"
click node_desktop "https://github.com/swaywm/sway/blob/master/sway/desktop/xdg_shell.c"
click node_input_manager "https://github.com/swaywm/sway/blob/master/sway/input/input-manager.c"
click node_seat "https://github.com/swaywm/sway/blob/master/sway/input/seat.c"
click node_ipc_server "https://github.com/swaywm/sway/blob/master/sway/ipc-server.c"
click node_ipc_json "https://github.com/swaywm/sway/blob/master/sway/ipc-json.c"
click node_ipc_client "https://github.com/swaywm/sway/blob/master/common/ipc-client.c"
click node_swaymsg "https://github.com/swaywm/sway/blob/master/swaymsg/main.c"
click node_swaybar "https://github.com/swaywm/sway/blob/master/swaybar/bar.c"
click node_swaynag "https://github.com/swaywm/sway/blob/master/swaynag/swaynag.c"
click node_drawing "https://github.com/swaywm/sway/blob/master/common/cairo.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_sway,node_server,node_config,node_commands,node_criteria,node_tree,node_arrange,node_transactions,node_desktop,node_wlroots toneBlue
class node_input_manager,node_seat toneAmber
class node_ipc_server,node_ipc_json,node_ipc_client toneMint
class node_swaymsg,node_swaybar,node_swaynag,node_drawing toneRose
class node_build toneNeutral
```

## Components

### Compositor Core

Primary Sway server, policy, desktop model, and rendering boundary.

- [sway compositor](https://github.com/swaywm/sway/blob/master/sway/main.c): executable · Primary compositor process. · `sway/main.c`
- [Server lifecycle](https://github.com/swaywm/sway/blob/master/sway/server.c): compositor state · Owns compositor-facing wlroots state. · `sway/server.c`
- [Config policy](https://github.com/swaywm/sway/blob/master/sway/config.c): configuration · Parses persistent input, output, bar, binding, and rule policy. · `sway/config.c`
- [Command dispatcher](https://github.com/swaywm/sway/blob/master/sway/commands.c): command engine · `sway/commands.c`
- [Criteria matcher](https://github.com/swaywm/sway/blob/master/sway/criteria.c): target selection · `sway/criteria.c`
- [Desktop tree](https://github.com/swaywm/sway/blob/master/sway/tree/root.c): window model · Canonical root, output, workspace, container, and view hierarchy. · `sway/tree/root.c`
- [Layout arrangement](https://github.com/swaywm/sway/blob/master/sway/tree/arrange.c): layout engine · Converts tiling and floating state into geometry. · `sway/tree/arrange.c`
- [Desktop transactions](https://github.com/swaywm/sway/blob/master/sway/desktop/transaction.c): state synchronization · Separates requested layout from client-committed visual state. · `sway/desktop/transaction.c`
- [Client protocol integration](https://github.com/swaywm/sway/blob/master/sway/desktop/xdg_shell.c): desktop protocols · XDG shell, layer shell, and optional Xwayland bridge. · `sway/desktop/xdg_shell.c`
- **wlroots / Wayland**: runtime boundary · Provides Wayland protocol, surface, output, and rendering primitives.

### Input

Device and seat interaction state machines.

- [Input manager](https://github.com/swaywm/sway/blob/master/sway/input/input-manager.c): device lifecycle · Maps libinput and wlroots device events into Sway input state. · `sway/input/input-manager.c`
- [Seats and interactions](https://github.com/swaywm/sway/blob/master/sway/input/seat.c): focus and pointer state · Mediates focus, cursor, and move/resize seat operations. · `sway/input/seat.c`

### IPC

i3-compatible external control and event transport.

- [IPC server](https://github.com/swaywm/sway/blob/master/sway/ipc-server.c): IPC endpoint · Publishes i3-compatible commands, queries, and events. · `sway/ipc-server.c`
- [IPC JSON](https://github.com/swaywm/sway/blob/master/sway/ipc-json.c): serialization · Serializes tree, workspace, input, output, and event data. · `sway/ipc-json.c`
- [IPC client transport](https://github.com/swaywm/sway/blob/master/common/ipc-client.c): shared transport · Reusable client connection layer. · `common/ipc-client.c`

### Companion Clients

Separate processes connected through IPC or Wayland.

- [swaymsg](https://github.com/swaywm/sway/blob/master/swaymsg/main.c): CLI executable · `swaymsg/main.c`
- [swaybar](https://github.com/swaywm/sway/blob/master/swaybar/bar.c): bar process · Consumes IPC and renders workspace, status, and tray UI. · `swaybar/bar.c`
- [swaynag](https://github.com/swaywm/sway/blob/master/swaynag/swaynag.c): Wayland UI process · Independent warning and error surface. · `swaynag/swaynag.c`
- [Shared drawing and buffers](https://github.com/swaywm/sway/blob/master/common/cairo.c): rendering utilities · Cairo/Pango drawing and Wayland buffer support. · `common/cairo.c`

### Other components

- [Meson/Ninja build](https://github.com/swaywm/sway/blob/master/meson.build): build system · `meson.build`

## Connections

- Meson/Ninja build → sway compositor: builds
- Meson/Ninja build → swaymsg: builds
- Meson/Ninja build → swaybar: builds
- Meson/Ninja build → swaynag: builds
- sway compositor → Server lifecycle: initializes
- sway compositor → Config policy: loads and reloads
- Server lifecycle → wlroots / Wayland: uses
- Client protocol integration → wlroots / Wayland: bridges clients through
- Config policy → Command dispatcher: defines commands for
- Command dispatcher → Criteria matcher: selects targets via
- Command dispatcher → Desktop tree: mutates
- Desktop tree → Layout arrangement: provides layout state
- Layout arrangement → Desktop transactions: requests geometry changes
- Desktop transactions → Client protocol integration: synchronizes clients
- Input manager → Seats and interactions: routes device events
- Seats and interactions → Desktop tree: updates focus and actions
- Input manager → wlroots / Wayland: uses input events
- IPC server → Command dispatcher: executes runtime commands
- IPC server → IPC JSON: serializes through
- IPC JSON → Desktop tree: queries state from
- swaymsg → IPC client transport: uses
- swaybar → IPC client transport: uses
- IPC client transport → IPC server: connects to
- swaybar → Shared drawing and buffers: renders with
- swaynag → Shared drawing and buffers: renders with
- swaynag → wlroots / Wayland: creates Wayland surface through
