# devolutions/ironrdp architecture

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

- Interactive diagram: https://gitdiagram.com/devolutions/ironrdp
- Repository: https://github.com/devolutions/ironrdp

## Overview

##### Project Purpose and Type
- IronRDP is a suite of Rust libraries (crates) that implements various parts of the RDP protocol. It serves both as a full client/server implementation and as lower-level libraries for things like protocol decoding/encoding, connection management, graphics rendering, clipboard redirection, and security (including TLS and CredSSP).
- The project also offers different usage patterns (blocking vs. non-blocking/async) and provides cross-interface support via FFI for integrations (e.g., .NET interop) and a web client (Svelte/JS frontend).

##### File Structure
- The “crates” directory contains many individual crates that each focus on one aspect of the protocol:
- Core protocol implementations: e.g., ironrdp-core, ironrdp-pdu, ironrdp-error.
- Connection modules: ironrdp-connector, ironrdp-acceptor, ironrdp-session.
- I/O variations: asynchronous (ironrdp-async), blocking (ironrdp-blocking), and tokio-based (ironrdp-tokio).
- Graphics and display modules: ironrdp-graphics, ironrdp-glutin-renderer, ironrdp-displaycontrol.
- Clipboard and multimedia: ironrdp-cliprdr, ironrdp-rdpsnd.
- Testing suites: ironrdp-testsuite-core and ironrdp-testsuite-extra.
- A separate “ffi” directory suggests interoperability layers (e.g., for .NET) and then there is a web-client for the remote GUI.
- Additionally, “xtask” is a custom tooling crate for automation (building, cleaning, versioning, fuzzing, etc.).

##### Main Components
a. Core Library and Protocol Handling:
– ironrdp-core: The central library for protocol primitives.
– ironrdp-pdu: Handles message encoding/decoding, encapsulating all PDUs.
– ironrdp-error: Central error handling.
b. Connection Handlers:
– ironrdp-connector and ironrdp-acceptor: Manage outbound/inbound connection setup.
– ironrdp-session: Maintains session state, including handshake, active stages, and finalization.
c. Communication Variants:
– Separate async, blocking, and tokio-based modules, which indicate that the project supports both non-blocking/asynchronous and blocking I/O models.
d. Media and Graphics:
– ironrdp-graphics and its sub-components (e.g., displaycontrol, glutin-renderer): Manage the decoding and rendering of graphics updates and handling of video codecs (RFX, raw, RLE, etc.).
e. Additional Functional Modules:
– Clipboard redirection (ironrdp-cliprdr, cliprdr-format, cliprdr-native).
– Audio handling (ironrdp-rdpsnd and its native version).
f. External Integrations and Interfaces:
– FFI layer under “ffi”: Offers bindings for .NET and possibly other languages.
– Web client modules (“web-client”): Split between iron-remote-gui and iron-svelte-client, representing the frontend user interface.
g. Testing and Automation:
– The testsuite crates and “fuzz” directory emphasize testing and fuzzing.
– “xtask” provides command-line operations for building, cleaning, testing, and deploying.

##### Relationships and Interactions
- That the connection handlers feed into the session management (ironrdp-session) where the handshake and activation occur.
- The graphics/decoder components (ironrdp-graphics, glutin-renderer, etc.) interact with the protocol modules by consuming decoded PDUs (for bitmap updates, pointer movements, etc.) and then rendering them.
- The clipboard, audio, and other peripheral channel modules work in parallel with the primary data stream.
- Integration points: the FFI layer and the web-client are consumers of the core libraries, exposing functionality via a .NET or JavaScript interface.

##### Architectural Patterns and Technologies
- Modular design: Each functionality is isolated into a separate crate for enhanced reusability and testing.
- Layered architecture: A core layer (protocol, error handling) underpins higher-level modules (session, rendering, channels).
- Support for multiple I/O paradigms (async, blocking, tokio-based): Emphasize separation of concerns within networking.
- Use of Rust’s package and dependency management (Cargo.toml, Cargo.lock) ensures each module’s dependencies are well-contained.
- FFI and Web integration: Illustrate how native Rust libraries interface with other environments (like .NET or JS via WebAssembly).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "External Interfaces and Clients"
        FFI["FFI Bridge"]:::external
        RemoteGUI["Remote GUI"]:::external
        Svelte["Svelte Client"]:::external
    end

    subgraph "Media, Clipboard, and Audio"
        Graphics["Graphics Processing"]:::media
        Renderer["Renderer"]:::media
        Display["Display Control"]:::media
        ClipboardPrimary["Clipboard Primary"]:::media
        ClipboardFormats["Clipboard Formats"]:::media
        ClipboardNative["Clipboard Native"]:::media
        Audio["Audio Handling"]:::media
        AudioNative["Audio Native"]:::media
    end

    subgraph "Connection and Session Management"
        Connector["Connector"]:::connection
        Acceptor["Acceptor"]:::connection
        Session["Session Management"]:::connection
        AsyncIO["Asynchronous I/O"]:::connection
        BlockingIO["Blocking I/O"]:::connection
        TokioIO["Tokio-Based I/O"]:::connection
    end

    subgraph "Core Protocol and Error Handling"
        Core["ironrdp-core"]:::core
        PDU["ironrdp-pdu"]:::core
        Error["ironrdp-error"]:::core
    end

    subgraph "Testing and Automation"
        TestsCore["Testsuite Core"]:::testing
        TestsExtra["Testsuite Extra"]:::testing
        Xtask["Custom Tooling (xtask)"]:::testing
    end

    %% Relationships between Connection and Session Management components
    Connector -->|"feeds"| Session
    Acceptor -->|"feeds"| Session
    AsyncIO -->|"async"| Session
    BlockingIO -->|"blocking"| Session
    TokioIO -->|"tokio"| Session

    %% Session using Core Protocol
    Session -->|"uses"| Core
    Session -->|"uses"| PDU
    Session -->|"uses"| Error

    %% Session feeding into Media, Clipboard, and Audio channels
    Session -->|"triggers"| Graphics
    Session -->|"updates"| ClipboardPrimary
    Session -->|"routes"| Audio

    %% Graphics subcomponents
    Graphics -->|"renders"| Renderer
    Graphics -->|"controls"| Display

    %% Clipboard subcomponents
    ClipboardPrimary -->|"formats"| ClipboardFormats
    ClipboardPrimary -->|"native"| ClipboardNative

    %% Session exposing functionality to External Interfaces
    Session -->|"exposes"| FFI
    Session -->|"exposes"| RemoteGUI
    Session -->|"exposes"| Svelte

    %% Testing and Automation interactions
    Xtask -->|"builds"| Session
    Xtask -->|"builds"| Core
    TestsCore -->|"tests"| Core
    TestsCore -->|"tests"| Session
    TestsExtra -->|"tests"| Core
    TestsExtra -->|"tests"| Session

    %% Click Events
    click Core "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-core"
    click PDU "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-pdu"
    click Error "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-error"
    
    click Acceptor "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-acceptor"
    click Connector "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-connector"
    click Session "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-session"
    
    click AsyncIO "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-async"
    click BlockingIO "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-blocking"
    click TokioIO "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-tokio"
    
    click Graphics "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-graphics"
    click Renderer "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-glutin-renderer"
    click Display "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-displaycontrol"
    
    click ClipboardPrimary "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-cliprdr"
    click ClipboardFormats "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-cliprdr-format"
    click ClipboardNative "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-cliprdr-native"
    
    click Audio "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-rdpsnd"
    click AudioNative "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-rdpsnd-native"
    
    click FFI "https://github.com/devolutions/ironrdp/tree/master/ffi"
    click RemoteGUI "https://github.com/devolutions/ironrdp/tree/master/web-client/iron-remote-gui"
    click Svelte "https://github.com/devolutions/ironrdp/tree/master/web-client/iron-svelte-client"
    
    click TestsCore "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-testsuite-core"
    click TestsExtra "https://github.com/devolutions/ironrdp/tree/master/crates/ironrdp-testsuite-extra"
    click Xtask "https://github.com/devolutions/ironrdp/tree/master/xtask"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef connection fill:#cff,stroke:#333,stroke-width:2px;
    classDef media fill:#fcf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffc,stroke:#333,stroke-width:2px;
```
