# smithay/wayland-rs architecture

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

- Interactive diagram: https://gitdiagram.com/smithay/wayland-rs
- Repository: https://github.com/smithay/wayland-rs

## Overview

##### Main Components
- Core API Crates:
- wayland-client – Provides client-side connection handling, event queues, and global management.
- wayland-server – Implements the server-side logic for handling connections, dispatching, and socket management.
- wayland-protocols – Centralizes the official protocol extension bindings.
- Auxiliary Crates:
- wayland-egl – Bridges Wayland with OpenGL, used in client-side rendering.
- wayland-cursor – Facilitates loading and managing system cursor images.
- Internal/Tooling Crates:
- wayland-backend – Contains the protocol logic implementation. Note its division into a pure Rust implementation and an FFI-based system backend.
- wayland-scanner – Processes XML protocol descriptions to generate Rust code, crucial for custom protocol extensibility.
- wayland-sys – Provides low-level bindings to C Wayland libraries for interoperability.
- Additional Testing Infrastructure:
- wayland-tests – Contains integration and unit tests to validate client and server behavior.

##### Relationships and Interactions
- The client- and server-side crates depend on wayland-protocols for the protocol definitions and extensions.
- wayland-scanner feeds generated code into several other crates (especially the backend and protocols libraries) which in turn are consumed by clients and servers.
- Auxiliary crates (wayland-egl and wayland-cursor) are usually used by the client to support rendering and UI elements.
- Tests (located in wayland-tests and specific tests folders) validate the interactions between these components, ensuring that changes in one part of the system (e.g., the backend or protocol definitions) propagate correctly to the public APIs.

##### Architectural Patterns and Design Principles
- Modularization: Each crate is isolated in functionality and can be understood or even used independently.
- Layered Design: Lower-level bindings (wayland-sys) support middle-layer logic (wayland-backend and wayland-scanner) that underpin the high-level APIs (client, server, and protocols).
- Code Generation: The use of wayland-scanner demonstrates an automated approach to converting XML protocol specifications into Rust code, emphasizing maintainability and extensibility.
- Dual Backend Implementation: In the case of the wayland-backend, the dual approach (native Rust vs. FFI-based) showcases the design flexibility regarding how protocol logic interacts with either pure Rust or external system libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client/Server Layer"
        WClient["wayland-client"]:::client
        WServer["wayland-server"]:::server
        WAYEGL["wayland-egl"]:::aux
        WAYCUR["wayland-cursor"]:::aux
    end

    subgraph "Protocol & Generation Layer"
        WProto["wayland-protocols"]:::protocol
        WProtoMisc["wayland-protocols-misc"]:::protocol
        WProtoPlasma["wayland-protocols-plasma"]:::protocol
        WProtoWlr["wayland-protocols-wlr"]:::protocol
        WScanner["wayland-scanner"]:::tool
    end

    subgraph "Backend/Interop Layer"
        WBackend["wayland-backend"]:::backend
        WSys["wayland-sys"]:::system
    end

    Tests["wayland-tests"]:::test

    %% Relationships between Client/Server and Protocol Layer
    WClient -->|"depends"| WProto
    WServer -->|"depends"| WProto

    WClient -->|"uses"| WAYEGL
    WClient -->|"uses"| WAYCUR

    %% Relationships from Protocol Generation to Backend/Interop
    WScanner -->|"generates"| WBackend
    WScanner -->|"generates"| WProto

    %% Backend implementation details
    WBackend -->|"FFI"| WSys

    %% Protocol contains additional extensions
    WProto -->|"includes"| WProtoMisc
    WProto -->|"includes"| WProtoPlasma
    WProto -->|"includes"| WProtoWlr

    %% Testing validates core components
    Tests --- WClient
    Tests --- WServer
    Tests --- WProto
    Tests --- WBackend

    %% Click Events
    click WClient "https://github.com/smithay/wayland-rs/tree/master/wayland-client"
    click WServer "https://github.com/smithay/wayland-rs/tree/master/wayland-server"
    click WProto "https://github.com/smithay/wayland-rs/tree/master/wayland-protocols"
    click WProtoMisc "https://github.com/smithay/wayland-rs/tree/master/wayland-protocols-misc"
    click WProtoPlasma "https://github.com/smithay/wayland-rs/tree/master/wayland-protocols-plasma"
    click WProtoWlr "https://github.com/smithay/wayland-rs/tree/master/wayland-protocols-wlr"
    click WAYEGL "https://github.com/smithay/wayland-rs/tree/master/wayland-egl"
    click WAYCUR "https://github.com/smithay/wayland-rs/tree/master/wayland-cursor"
    click WBackend "https://github.com/smithay/wayland-rs/tree/master/wayland-backend"
    click WScanner "https://github.com/smithay/wayland-rs/tree/master/wayland-scanner"
    click WSys "https://github.com/smithay/wayland-rs/tree/master/wayland-sys"
    click Tests "https://github.com/smithay/wayland-rs/tree/master/wayland-tests"

    %% Styles
    classDef client fill:#FAD02E,stroke:#333,stroke-width:1px;
    classDef server fill:#F28C8C,stroke:#333,stroke-width:1px;
    classDef aux fill:#A0CED9,stroke:#333,stroke-width:1px;
    classDef protocol fill:#C3B1E1,stroke:#333,stroke-width:1px;
    classDef tool fill:#F4A261,stroke:#333,stroke-width:1px;
    classDef backend fill:#B3DE69,stroke:#333,stroke-width:1px;
    classDef system fill:#8EC6C5,stroke:#333,stroke-width:1px;
    classDef test fill:#FAF0BE,stroke:#333,stroke-width:1px;
```
