# mathslinux/vd_agent architecture

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

- Interactive diagram: https://gitdiagram.com/mathslinux/vd_agent
- Repository: https://github.com/mathslinux/vd_agent

## Overview

##### Main Components
- Daemon Component (spice-vdagentd): This runs as a background service and, as indicated by multiple source files (e.g., spice-vdagentd.c, spice-vdagentd-uinput.c, spice-vdagentd-xorg-conf.c) and configuration files in the “data” directory, is responsible for integrating with system services (such as the kernel via uinput) and external management (like systemd and sys-v initscripts).
- X-Session Agent (spice-vdagent): A per-session process that launches in the active X-session. Its job is to communicate with the daemon for capturing and adjusting display/resolution, handling client input and facilitating clipboard functionality.
- Communication Channel: The agent and daemon use a dedicated communication channel over a single virtio serial port (with distinct names depending on the OS – e.g., /dev/virtio-ports/com.redhat.spice.0 on Linux).
- External Interfaces: Include the configurations and integration points such as:
- Startup mechanisms via Sys-V initscripts, systemd service files, and XDG autostart (indicated in the “data” directory).
- X configuration adjustments (using Xrandr for dynamic resolution or, in some cases, Xinerama for multiple display setups).

##### Relationships and Interactions
- The daemon (spice-vdagentd) is started at boot (through system/rc scripts) and monitors/controls the active X-session.
- The per-session agent (spice-vdagent) starts automatically (via Desktop Environment autostart) and communicates with the daemon to determine session statistics and mouse mode capabilities.
- Data flow: Input events (like mouse and clipboard) and configuration data are exchanged between the agent and daemon through the virtio serial port.
- On the system host (outside the guest), a Spice client (spicec) communicates with these agents via the behind-the-scenes virtio serial port.

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: Clear division between the persistent background daemon and the per-session process.
- Event-driven communication: Handling input events and dynamic display changes.
- Integration with system services: Using configuration files (systemd, udev rules, xorg configurations) allows for a mature and systemic integration with Linux infrastructure.
- Compatibility / Adaptability: Conditional support for older distributions (with or without console-kit) and multiple display handling strategies (Xinerama vs. Xrandr).

##### Relevant Technologies and Frameworks
- Linux system components: kernel input subsystem via uinput, systemd/service management, console kit (where applicable) and X11 integration.
- Virtualization interfaces: Virtio serial ports used for bridging the guest and host communications.
- X window system components: Xinerama and Xrandr for multi-display support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% System Integration
    SS["System Services (systemd,Sys-V)"]:::integration

    %% Daemon Component Node
    D["spice-vdagentd (Daemon)"]:::daemon
    SS -->|"starts_on_boot"| D

    %% Daemon Details Subgraph
    subgraph "Daemon Details"
        direction TB
        Dsrc["Source Code"]:::internal
        Dsrc1["vdagentd.c"]:::internal
        Dsrc2["vdagentd-uinput.c"]:::internal
        Dsrc3["vdagentd-xorg-conf.c"]:::internal
        Dsrc -->|"includes"| Dsrc1
        Dsrc -->|"includes"| Dsrc2
        Dsrc -->|"includes"| Dsrc3

        Dconf["Configuration Files"]:::integration
        Dconf1["spice-vdagentd.service"]:::integration
        Dconf2["spice-vdagentd"]:::integration
        Dconf3["70-spice-vdagentd.rules"]:::integration
        Dconf4["spice-vdagentd.target"]:::integration
        Dconf5["spice-vdagentd.conf"]:::integration
        Dconf6["rsyslog.d"]:::integration
        Dconf7["modules-load.d"]:::integration
        Dconf -->|"contains"| Dconf1
        Dconf -->|"contains"| Dconf2
        Dconf -->|"contains"| Dconf3
        Dconf -->|"contains"| Dconf4
        Dconf -->|"contains"| Dconf5
        Dconf -->|"contains"| Dconf6
        Dconf -->|"contains"| Dconf7
    end

    D -->|"uses"| Dsrc
    D -->|"configured_by"| Dconf

    %% Daemon Integrations
    subgraph "Daemon Integrations"
        K["Kernel (uinput)"]:::integration
        X["X Configuration (Xrandr/Xorg)"]:::integration
    end
    D -->|"triggers"| K
    D -->|"updates"| X

    %% Communication Channel
    V["Virtio Serial Channel"]:::channel
    D -->|"communicates_via"| V

    %% Agent Component Subgraph
    subgraph "X-Session Agent"
        direction TB
        A["spice-vdagent (X-Session Agent)"]:::agent
        subgraph "Agent Source Code"
            Asrc1["vdagent.c"]:::internal
            Asrc2["vdagent-x11.c"]:::internal
            Asrc3["vdagent-x11-priv.h"]:::internal
        end
        A -->|"includes"| Asrc1
        A -->|"includes"| Asrc2
        A -->|"includes"| Asrc3
        Aauto["spice-vdagent.desktop"]:::integration
        A -->|"auto-started_by"| Aauto
    end

    V <-->|"commands,input,clipboard"| A
    V -->|"external_comm"| SC["Spice Client"]:::external

    %% Click Events for Daemon Component Source Code
    click Dsrc1 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagentd.c"
    click Dsrc2 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagentd-uinput.c"
    click Dsrc3 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagentd-xorg-conf.c"

    %% Click Events for Daemon Component Configuration Files
    click Dconf1 "https://github.com/mathslinux/vd_agent/blob/master/data/spice-vdagentd.service"
    click Dconf2 "https://github.com/mathslinux/vd_agent/tree/master/data/spice-vdagentd"
    click Dconf3 "https://github.com/mathslinux/vd_agent/blob/master/data/70-spice-vdagentd.rules"
    click Dconf4 "https://github.com/mathslinux/vd_agent/blob/master/data/spice-vdagentd.target"
    click Dconf5 "https://github.com/mathslinux/vd_agent/blob/master/data/tmpfiles.d/spice-vdagentd.conf"
    click Dconf6 "https://github.com/mathslinux/vd_agent/blob/master/data/rsyslog.d"
    click Dconf7 "https://github.com/mathslinux/vd_agent/blob/master/data/modules-load.d"

    %% Click Events for Agent Component Source Code and Autostart
    click Asrc1 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagent.c"
    click Asrc2 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagent-x11.c"
    click Asrc3 "https://github.com/mathslinux/vd_agent/blob/master/src/vdagent-x11-priv.h"
    click Aauto "https://github.com/mathslinux/vd_agent/blob/master/data/spice-vdagent.desktop"

    %% Click Events for Communication Channel
    click V "https://github.com/mathslinux/vd_agent/blob/master/src/vdagent-virtio-port.c"

    %% Styles
    classDef daemon fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef agent fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef integration fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef internal fill:#D5F5E3,stroke:#1D8348,stroke-width:2px;
    classDef channel fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
