# apache/guacamole-server architecture

> Architecture diagram of the GitHub repository apache/guacamole-server, 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/apache/guacamole-server
- Repository: https://github.com/apache/guacamole-server

## Overview

Step-by-step guidelines:

##### Main Components
- guacd Daemon: This is the central proxy process that listens for client connections (default port 4822). It translates between Guacamole’s own text-based protocol and the underlying remote desktop protocols.
- libguac: A core library providing common functionality, shared among guacd and the individual protocol modules.
- Protocol Modules: Located under src/protocols, each subdirectory (e.g., rdp, ssh, telnet, vnc, kubernetes) represents a module that implements support for that respective protocol. They handle protocol-specific details, convert data between binary and the text-based Guacamole protocol, and interact with libguac.
- Auxiliary Utilities: Other tools like guacenc (a video encoding utility) and guacctl/guacget (under bin) which serve as supplementary components.
- External Dependencies: Although not drawn as internal modules, acknowledge dependencies to external libraries such as Cairo, libjpeg(-turbo), libpng, FreeRDP, libssh2, OpenSSL, and others that are needed for rendering, protocol implementation, and feature support.
- Build & Configuration: Use configuration files (configure.ac, Makefile.am files) to indicate the build structure. Though these aren’t runtime components, you might note the use of GNU Automake and the configuration process for completeness.

##### Relationships and Interactions
- guacd is the central component that utilizes libguac and communicates with various protocol modules.

##### Architecturally Relevant Patterns and Principles
- Modular Architecture: Emphasize that each protocol support (rdp, ssh, telnet, vnc, etc.) is implemented in its own module, making the design extensible.
- Abstraction through libguac: Use of a central library to encapsulate common routines (such as handling display, input, and error reporting) that streamlines the protocol module implementations.
- Separation of Concerns: The design clearly separates the network-facing daemon (guacd) from the protocol-specific operations.

##### Essential Architectural Elements in Detail
- Significant directories (common, protocols, guacd, libguac) are represented as architectural modules.
- That many of the source directories (like tests and docs) are not part of the runtime architecture but indicate the project's emphasis on quality and documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Guacamole Client"]:::external

    %% Core Components
    subgraph "Core Components"
        A["Proxy Daemon - guacd (port 4822)"]:::core
        B["Common Library - libguac"]:::core

        subgraph "Protocol Modules"
            RDP["Protocol Module: RDP"]:::protocol
            SSH["Protocol Module: SSH"]:::protocol
            Telnet["Protocol Module: Telnet"]:::protocol
            VNC["Protocol Module: VNC"]:::protocol
            K8s["Protocol Module: Kubernetes"]:::protocol
        end
    end

    %% Auxiliary Utilities
    subgraph "Auxiliary Utilities"
        ENC["Video Encoder Utility - guacenc"]:::utility
        CTL["Utility - guacctl"]:::utility
        GET["Utility - guacget"]:::utility
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        BUILD["Build & Configuration Files"]:::build
    end

    %% External Dependencies
    EXT["External Dependencies:\nCairo, libjpeg-turbo, libpng,\nFreeRDP, libssh2, OpenSSL, etc."]:::external

    %% Connections between External Client and Core Components
    Client -->|"connects"| A

    %% guacd interactions with libguac and Protocol Modules
    A -->|"uses"| B
    A -->|"translates"| RDP
    A -->|"translates"| SSH
    A -->|"translates"| Telnet
    A -->|"translates"| VNC
    A -->|"translates"| K8s

    %% Protocol Modules depend on libguac
    RDP -->|"depends_on"| B
    SSH -->|"depends_on"| B
    Telnet -->|"depends_on"| B
    VNC -->|"depends_on"| B
    K8s -->|"depends_on"| B

    %% Auxiliary Utilities connections
    A -->|"controls/logs"| CTL
    A -->|"controls/logs"| GET
    A -->|"encodes video"| ENC

    %% Build & Configuration relationships
    BUILD -->|"defines build process for"| A
    BUILD -->|"defines build process for"| B

    %% External Dependencies required by multiple components
    A ---|"requires"| EXT
    B ---|"requires"| EXT
    RDP ---|"requires"| EXT
    SSH ---|"requires"| EXT
    Telnet ---|"requires"| EXT
    VNC ---|"requires"| EXT
    K8s ---|"requires"| EXT

    %% Click Events
    click A "https://github.com/apache/guacamole-server/tree/main/src/guacd"
    click B "https://github.com/apache/guacamole-server/tree/main/src/libguac"
    click RDP "https://github.com/apache/guacamole-server/tree/main/src/protocols/rdp"
    click SSH "https://github.com/apache/guacamole-server/tree/main/src/protocols/ssh"
    click Telnet "https://github.com/apache/guacamole-server/tree/main/src/protocols/telnet"
    click VNC "https://github.com/apache/guacamole-server/tree/main/src/protocols/vnc"
    click K8s "https://github.com/apache/guacamole-server/tree/main/src/protocols/kubernetes"
    click ENC "https://github.com/apache/guacamole-server/tree/main/src/guacenc"
    click CTL "https://github.com/apache/guacamole-server/tree/main/bin/guacctl"
    click GET "https://github.com/apache/guacamole-server/tree/main/bin/guacget"
    click BUILD "https://github.com/apache/guacamole-server/blob/main/configure.ac"

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef protocol fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef utility fill:#abebc6,stroke:#239b56,stroke-width:2px;
    classDef build fill:#f5cba7,stroke:#a04000,stroke-width:2px;
    classDef external fill:#f9c0c0,stroke:#c0392b,stroke-width:2px;
```
