# libvnc/x11vnc architecture

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

- Interactive diagram: https://gitdiagram.com/libvnc/x11vnc
- Repository: https://github.com/libvnc/x11vnc

## Overview

##### Project type and purpose
- This is x11vnc, a native C-based VNC server that allows remote control of an existing X11 display.
- It provides screen capture (via Xlib/XDamage/Xrandr), input injection (via uinput or XTest), optional SSL/TLS support, mDNS/Avahi discovery, and a minimal local “console” GUI.

##### File structure
- Top level:
- src/ – core C modules for screen capture, encoding, network, input, SSL, X11-specific backends (macOS, Linux framebuffer)
- misc/ – assorted helper scripts, sample client wrappers, alternate viewers (Enhanced TightVNC viewer for Windows/macOS)
- doc/ – FAQ, options, SSL portal guide, Sunray and other protocol notes
- configure.ac, Makefile.am, autogen.sh – autotools build
- Key modules in src/:
- x11vnc.c (main loop, RFB protocol)
- xdamage.c, xrandr.c, xinerama.c (incremental update detection)
- sslhelper.c, sslcmds.c (TLS handshake and encryption)
- connections.c (manage client sockets)
- userinput.c, uinput.c (keyboard/mouse injection)
- avahi.c (mDNS service advertisement)
- gui.c (local curses or simple ASCII console UI)

##### (minimal) README and docs
- Although the top-level README is a placeholder, the doc/ directory and man page (x11vnc.1) describe architecture: capture → encode → transmit → input injection.

##### Components
a. Main components:
1. Client Viewer(s) (e.g. standard VNC viewer or Enhanced TightVNC viewer)
2. Network Stack (TCP sockets, optional SSL/TLS layer)
3. x11vnc Core Server
– X11 Interface (Xlib, XDamage, Xrandr, Xinerama)
– Framebuffer Capture Engine
– RFB Encoder (raw, tight, hextile, turbojpeg)
– Connection Manager
– Input Injection Handler (uinput or XTest)
– Configuration/UI Module (gui.c)
4. Dependencies / Extensions
– Avahi/mDNS Discovery
– SSL/TLS library (OpenSSL)
– Operating-system backends (Linux framebuffer, macOS CG)
b. Relationships and interactions:
– Viewer ↔ Network Stack: RFB handshake, pixel data, input events
– Network Stack ↔ SSL Module (optional): encapsulate RFB in TLS
– Server Core ↔ X11 Interface: capture screen updates, monitor damage events
– Server Core ↔ Encoder: compress and packetize raw pixels
– Server Core ↔ Connection Manager: spawn per-client thread, track state
– Server Core ↔ Input Injection: receive events, post to X server or uinput driver
– Server Core ↔ Avahi: publish & remove mDNS service on startup/exit
c. Architectural patterns / design principles:
– Modular C code with clear separation: capture, encode, network, UI, input
– Plugin-style backends for different OS and features (SSL, Avahi, Linux FB)
– Event-driven loop with multi-threaded or multiplexed I/O for multiple clients
d. Key technologies / libraries:
– Xlib, XDamage, Xrandr, Xinerama, XTest
– libavahi-client (mDNS)
– OpenSSL (optional)
– Linux uinput (/dev/uinput)
– pthreads or select()/poll() for concurrency
– autotools for build/configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "Clients"
        direction TB
        Viewer["Client Viewer\n(Enhanced TightVNC)"]:::external
        click Viewer "https://github.com/libvnc/x11vnc/tree/master/misc/enhanced_tightvnc_viewer"
    end

    %% Network and Transport
    subgraph "Network Layer"
        direction TB
        NetStack["TCP/IP Stack"]:::network
        click NetStack "https://github.com/libvnc/x11vnc/blob/master/src/inet.c"
        click NetStack "https://github.com/libvnc/x11vnc/blob/master/src/inet.h"
        SSL["SSL/TLS Layer"]:::optional
        click SSL "https://github.com/libvnc/x11vnc/blob/master/src/sslhelper.c"
        click SSL "https://github.com/libvnc/x11vnc/blob/master/src/sslhelper.h"
        click SSL "https://github.com/libvnc/x11vnc/blob/master/src/sslcmds.c"
        click SSL "https://github.com/libvnc/x11vnc/blob/master/src/sslcmds.h"
    end

    %% Core Server
    subgraph "x11vnc Core Server" 
        direction TB
        CoreMain["Main Loop & RFB Protocol\n(x11vnc.c)"]:::core
        click CoreMain "https://github.com/libvnc/x11vnc/blob/master/src/x11vnc.c"
        click CoreMain "https://github.com/libvnc/x11vnc/blob/master/src/x11vnc.h"
        click CoreMain "https://github.com/libvnc/x11vnc/blob/master/src/x11vnc_defs.c"

        %% Capture & Update
        subgraph "Capture & Update" 
            direction TB
            XDamage["XDamage Monitor"]:::capture
            click XDamage "https://github.com/libvnc/x11vnc/blob/master/src/xdamage.c"
            click XDamage "https://github.com/libvnc/x11vnc/blob/master/src/xdamage.h"
            XRandR["XRandR Monitor"]:::capture
            click XRandR "https://github.com/libvnc/x11vnc/blob/master/src/xrandr.c"
            click XRandR "https://github.com/libvnc/x11vnc/blob/master/src/xrandr.h"
            Xinerama["Xinerama Monitor"]:::capture
            click Xinerama "https://github.com/libvnc/x11vnc/blob/master/src/xinerama.c"
            click Xinerama "https://github.com/libvnc/x11vnc/blob/master/src/xinerama.h"
            Screen["Framebuffer Capture"]:::capture
            click Screen "https://github.com/libvnc/x11vnc/blob/master/src/screen.c"
            click Screen "https://github.com/libvnc/x11vnc/blob/master/src/screen.h"
            %% OS Backends
            subgraph "OS Backends" 
                direction TB
                LinuxFB["Linux Framebuffer"]:::optional
                click LinuxFB "https://github.com/libvnc/x11vnc/blob/master/src/linuxfb.c"
                click LinuxFB "https://github.com/libvnc/x11vnc/blob/master/src/linuxfb.h"
                MacCG["macOS CoreGraphics"]:::optional
                click MacCG "https://github.com/libvnc/x11vnc/blob/master/src/macosxCG.c"
                click MacCG "https://github.com/libvnc/x11vnc/blob/master/src/macosxCG.h"
                MacGL["macOS OpenGL"]:::optional
                click MacGL "https://github.com/libvnc/x11vnc/blob/master/src/macosx_opengl.c"
                click MacGL "https://github.com/libvnc/x11vnc/blob/master/src/macosx_opengl.h"
                MacGen["Generic macOS"]:::optional
                click MacGen "https://github.com/libvnc/x11vnc/blob/master/src/macosx.c"
                click MacGen "https://github.com/libvnc/x11vnc/blob/master/src/macosx.h"
            end
        end

        %% Encoding
        subgraph "RFB Encoder" 
            direction TB
            Encoder["Encoding Definitions\n(enc.h)"]:::encode
            click Encoder "https://github.com/libvnc/x11vnc/blob/master/src/enc.h"
        end

        %% Connection Management
        subgraph "Connection Manager"
            direction TB
            ConnMgr["Connections Manager"]:::network
            click ConnMgr "https://github.com/libvnc/x11vnc/blob/master/src/connections.c"
            click ConnMgr "https://github.com/libvnc/x11vnc/blob/master/src/connections.h"
        end

        %% Input Injection
        subgraph "Input Injection"
            direction TB
            XTest["XTest & High-level Input"]:::input
            click XTest "https://github.com/libvnc/x11vnc/blob/master/src/userinput.c"
            click XTest "https://github.com/libvnc/x11vnc/blob/master/src/userinput.h"
            UInput["uinput (Linux)"]:::input
            click UInput "https://github.com/libvnc/x11vnc/blob/master/src/uinput.c"
            click UInput "https://github.com/libvnc/x11vnc/blob/master/src/uinput.h"
            Keyboard["Keyboard Helpers"]:::input
            click Keyboard "https://github.com/libvnc/x11vnc/blob/master/src/keyboard.c"
            click Keyboard "https://github.com/libvnc/x11vnc/blob/master/src/keyboard.h"
            Cursor["Pointer Helpers"]:::input
            click Cursor "https://github.com/libvnc/x11vnc/blob/master/src/cursor.c"
            click Cursor "https://github.com/libvnc/x11vnc/blob/master/src/cursor.h"
        end

        %% Configuration and UI
        subgraph "Config & UI"
            direction TB
            UI["Console GUI & Options"]:::ui
            click UI "https://github.com/libvnc/x11vnc/blob/master/src/gui.c"
            click UI "https://github.com/libvnc/x11vnc/blob/master/src/gui.h"
            click UI "https://github.com/libvnc/x11vnc/blob/master/src/options.c"
            click UI "https://github.com/libvnc/x11vnc/blob/master/src/options.h"
        end

        %% Avahi/mDNS
        Avahi["Avahi/mDNS Discovery"]:::optional
        click Avahi "https://github.com/libvnc/x11vnc/blob/master/src/avahi.c"
        click Avahi "https://github.com/libvnc/x11vnc/blob/master/src/avahi.h"
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        FAQ["FAQ"]:::optional
        click FAQ "https://github.com/libvnc/x11vnc/blob/master/doc/FAQ.md"
        OPTIONS["Options Guide"]:::optional
        click OPTIONS "https://github.com/libvnc/x11vnc/blob/master/doc/OPTIONS.md"
        SSLPORTAL["SSL Portal Guide"]:::optional
        click SSLPORTAL "https://github.com/libvnc/x11vnc/blob/master/doc/SSL-PORTAL.md"
        MAN["Man Page"]:::optional
        click MAN "https://github.com/libvnc/x11vnc/blob/master/x11vnc.1"
    end

    %% Data Flow
    Viewer -->|"RFB over TCP"| NetStack
    NetStack -->|Optional TLS| SSL
    SSL -->|RFB Data| ConnMgr
    NetStack -->|RFB Data| ConnMgr
    ConnMgr --> CoreMain
    CoreMain --> XDamage
    CoreMain --> XRandR
    CoreMain --> Xinerama
    CoreMain --> Screen
    Screen --> Encoder
    Encoder --> ConnMgr
    ConnMgr --> NetStack
    Viewer <--|Input Events| NetStack
    NetStack --> ConnMgr
    ConnMgr --> XTest
    XTest --> CoreMain
    ConnMgr --> UInput
    UInput --> CoreMain
    CoreMain --> Avahi

    XServer["X Server"]:::external
    XDamage --> XServer
    XRandR --> XServer
    Xinerama --> XServer
    XTest --> XServer
    UInput --> XServer

    %% Styles
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef network fill:#8fd3f4,stroke:#333,stroke-width:1px
    classDef capture fill:#b2f4b5,stroke:#333,stroke-width:1px
    classDef encode fill:#a0f4d3,stroke:#333,stroke-width:1px
    classDef input fill:#f4c38d,stroke:#333,stroke-width:1px
    classDef ui fill:#f4e38d,stroke:#333,stroke-width:1px
    classDef core fill:#f4d38d,stroke:#333,stroke-width:1px
    classDef optional fill:#d3d3d3,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px
```
