# dbus2/zbus architecture

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

- Interactive diagram: https://gitdiagram.com/dbus2/zbus
- Repository: https://github.com/dbus2/zbus

## Overview

Based on an analysis of the file tree and README, the project is a multi-crate Rust library that provides a safe, high- and low-level API for interacting with D‑Bus. In essence, it is a communication framework that lets developers build both D‑Bus services and clients in Rust—with additional utilities for handling serialization (wire formats), introspection XML, and generating code from interface definitions.

##### Main Components
- Core API Crate (“zbus”): This is the heart of the project that implements connection handling (both asynchronous and blocking), the D‑Bus protocol, authentication/handshake, and message management.
- Macros & Code Generation (“zbus_macros”): Provides macros to define D‑Bus interfaces and proxy types, reducing boilerplate code.
- Data Serialization (“zvariant” and “zvariant_derive”): Handles conversion of Rust data types to and from the D‑Bus wire format, including support for GVariant formatting.
- Name Handling (“zbus_names”): Manages D‑Bus bus names, interface names, member names, etc.
- XML / Introspection (“zbus_xml” and “zbus_xmlgen”): “zbus_xml” handles D‑Bus introspection XML processing and “zbus_xmlgen” is a tool (with both CLI and library components) that generates Rust code based on XML interface descriptions.
- Additional Utilities: Other supporting libraries (like “zvariant_utils”) that provide helper functions for signature processing, serialized data, and possibly error handling across the ecosystem.

##### Relationships and Interactions
- zbus ↔ zbus_names: The API and other modules use the types from zbus_names for managing names and identifiers.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the separation of concerns in distinct crates (for instance, API versus serialization versus XML processing). Indicate how these are independent but integrated through clearly defined APIs.

##### Relevant Technologies and Frameworks
- Rust as the Programming Language: Note the use of asynchronous primitives (with tokio examples provided in the README) and the ecosystem’s reliance on Rust’s type safety.
- D‑Bus Protocol: Highlight that the project implements/D‑Bus specific protocols, including authentication and naming protocols, which are core to many of the modules.
- CI/CD and Testing: Although not part of the runtime architecture, note that integration/CI files (like GitHub workflows and tests) indicate a robust development workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    user["User Code"]:::user
    zbus["zbus (Core API)"]:::zbus
    zbus_macros["zbus_macros"]:::macros
    zvariant["zvariant"]:::zvariant
    zvariant_derive["zvariant_derive"]:::zvariantDerive
    zbus_names["zbus_names"]:::zbusNames
    zbus_xml["zbus_xml"]:::zbusXML
    zbus_xmlgen["zbus_xmlgen"]:::zbusXMLgen
    zvariant_utils["zvariant_utils"]:::zvariantUtils

    %% User interactions
    user -->|"calls_API"| zbus
    user -->|"uses_macros"| zbus_macros

    %% zbus internal modules subgraph
    subgraph "zbus Internal Modules"
        async_conn["Async Connection"]:::internal
        blocking_conn["Blocking Connection"]:::internal
        handshake["Handshake"]:::internal
        socket_msg["Socket (Message Management)"]:::internal
    end

    %% zbus connections to its modules
    zbus -->|"internal"| async_conn
    zbus -->|"internal"| blocking_conn
    zbus -->|"internal"| handshake
    zbus -->|"internal"| socket_msg

    %% zbus dependencies
    zbus -->|"serialize"| zvariant
    zbus -->|"derive_helper"| zvariant_derive
    zbus -->|"name_resolution"| zbus_names
    zbus -->|"utilities"| zvariant_utils

    %% XML processing for introspection and code generation
    zbus_xml -->|"XML_introspection"| zbus_xmlgen
    zbus_xmlgen -->|"generated_code"| user

    %% Click Events
    click zbus "https://github.com/dbus2/zbus/tree/main/zbus/"
    click zbus_macros "https://github.com/dbus2/zbus/tree/main/zbus_macros/"
    click zvariant "https://github.com/dbus2/zbus/tree/main/zvariant/"
    click zvariant_derive "https://github.com/dbus2/zbus/tree/main/zvariant_derive/"
    click zbus_names "https://github.com/dbus2/zbus/tree/main/zbus_names/"
    click zbus_xml "https://github.com/dbus2/zbus/tree/main/zbus_xml/"
    click zbus_xmlgen "https://github.com/dbus2/zbus/tree/main/zbus_xmlgen/"
    click zvariant_utils "https://github.com/dbus2/zbus/tree/main/zvariant_utils/"

    %% Styles
    classDef user fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef zbus fill:#f94144,stroke:#333,stroke-width:2px;
    classDef macros fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef zvariant fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef zvariantDerive fill:#4d908e,stroke:#333,stroke-width:2px;
    classDef zbusNames fill:#f8961e,stroke:#333,stroke-width:2px;
    classDef zbusXML fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef zbusXMLgen fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef zvariantUtils fill:#277da1,stroke:#333,stroke-width:2px;
    classDef internal fill:#ffcc00,stroke:#333,stroke-width:2px;
```
