# libvnc/libvncserver architecture

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

- Interactive diagram: https://gitdiagram.com/libvnc/libvncserver
- Repository: https://github.com/libvnc/libvncserver
- Video tour (about a minute): https://gitdiagram.com/libvnc/libvncserver/video

## Overview

1. **What this repository is**
   LibVNCServer is a C library project that produces two main runtime artifacts: **`libvncserver`** for implementing VNC servers and **`libvncclient`** for implementing VNC clients. The repo is organized around the RFB/VNC protocol, not around an application UI or daemon by itself.

2. **Public boundary**
   The primary API surface is under **`include/rfb/`**. Those headers define the types and protocol-facing contracts that downstream applications use to embed VNC server/client behavior. The rest of the tree is the implementation behind that API.

3. **Shared infrastructure**
   **`src/common/`** contains code reused by both libraries: base64, socket helpers, authentication primitives, crypto backends, compression helpers, and utility code such as TurboJPEG and ZRLE-related helpers. This is the shared “platform layer” beneath both the server and client stacks.

4. **Server-side architecture**
   **`src/libvncserver/`** is the server pipeline. It owns framebuffer export, input/cut-and-paste handling, statistics, scaling, cursor handling, and the RFB handshake/session logic. Applications using the server library typically feed framebuffer updates into this layer and receive client input events back out.

5. **Client-side architecture**
   **`src/libvncclient/`** is the client pipeline. It owns connection setup, listening/reverse-connection support, decoding framebuffer updates, and client-side authentication/transport negotiation. A consuming app uses this library to connect to a remote RFB server and render or process updates.

6. **Protocol implementation split**
   Both libraries implement the same VNC/RFB wire protocol, but with different responsibilities. The repo supports multiple **encodings** such as Raw, CopyRect, Hextile, Zlib, Tight, Ultra, ZRLE, and ZYWRLE; the server side encodes framebuffer data for transport, while the client side decodes it. The shared protocol definitions live in the public headers and are reflected in the separate encoder/decoder source files in each library.

7. **Transport and security boundaries**
   Transport is layered underneath RFB. The project supports plain TCP RFB plus **WebSockets** on the server side, and encrypted RFB/WebSocket paths depending on build options. Security backends are pluggable at compile time: **OpenSSL**, **GnuTLS**, or **libgcrypt**/built-in crypto for different authentication and TLS capabilities. The architecture therefore has a clear “protocol above, transport/security below” split.

8. **Web delivery path**
   The server library includes **`websockets.c`** and related decoding support to expose VNC sessions through a browser-friendly WebSocket endpoint. The **`webclients/`** directory and bundled **noVNC** submodule provide the browser-side viewer assets that connect to that server endpoint. This is an integration path, not core protocol logic.

9. **Optional server features**
   The server side also includes optional subsystems such as **HTTP serving** for the web client bootstrap, **TightVNC file transfer** support, and various framebuffer transformation helpers. These are additional capabilities layered onto the core RFB session engine rather than separate services.

10. **Examples as integration references**
   The **`examples/server/`** and **`examples/client/`** trees are not part of the core library boundary; they are concrete consumer programs demonstrating how to wire framebuffer sources, input callbacks, tunneling, and viewer behavior. Architecturally, they show the intended embedding model for each library.

11. **Testing and verification**
   **`test/`** contains unit, integration, fuzz, and WebSocket-related tests. The presence of fuzz targets and WebSocket test data indicates that protocol parsing, encoding/decoding, and transport handling are treated as the most security-sensitive boundaries. CI, CodeQL, and fuzz workflows reinforce that this is a library with a large attack surface rather than a simple local app.

12. **Build and packaging**
   The project is built with **CMake** and exports both libraries via installable package metadata (`pkg-config` and CMake config files). The repo also includes cross-compilation support, especially for Windows/MinGW, which matters because the architecture is intended to be embedded into many host applications across platforms.

13. **How to draw the diagram**
   The clearest diagram is a layered one: **consumer applications/examples** at the top, then **`libvncclient`** and **`libvncserver`** as the two major API/runtime blocks, then a shared **`src/common`** foundation, and below that **TCP/WebSocket + TLS/crypto backends** feeding the RFB wire protocol. Around the core, show **examples**, **webclients/noVNC**, and **tests/CI** as supporting integration and validation subsystems.

Main entry points: [`src/libvncserver`](https://github.com/libvnc/libvncserver/tree/master/src/libvncserver) (libvncserver), [`src/common`](https://github.com/libvnc/libvncserver/tree/master/src/common) (Common code), [`src/libvncclient`](https://github.com/libvnc/libvncserver/tree/master/src/libvncclient) (libvncclient), [`CMakeLists.txt`](https://github.com/libvnc/libvncserver/blob/master/CMakeLists.txt) (Build system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_public["Public API"]
  node_n_include_rfb["Public headers<br/>API surface"]
end

subgraph group_g_runtime["Runtime libs"]
  node_n_server["libvncserver<br/>VNC server lib"]
  node_n_client["libvncclient<br/>VNC client lib"]
  node_n_server_session["Server core<br/>session engine<br/>[rfbserver.c]"]
  node_n_server_enc["Server encoders<br/>framebuffer encoders<br/>[zrle.c]"]
  node_n_server_ws["WebSocket path<br/>web transport<br/>[websockets.c]"]
  node_n_server_http["HTTP bootstrap<br/>web support<br/>[httpd.c]"]
  node_n_server_ft["File transfer<br/>optional feature<br/>[rfbtightserver.c]"]
  node_n_client_conn["Client core<br/>connection engine<br/>[rfbclient.c]"]
  node_n_client_dec["Client decoders<br/>framebuffer decoders<br/>[zrle.c]"]
end

subgraph group_g_shared["Shared foundation"]
  node_n_common["Common code<br/>shared infra"]
  node_n_protocol["RFB protocol<br/>wire protocol<br/>[rfbproto.h]"]
  node_n_crypto["Crypto backends<br/>security layer<br/>[crypto.h]"]
  node_n_sockets["Sockets<br/>transport layer<br/>[sockets.c]"]
  node_n_compress["Compression<br/>encoding support<br/>[minilzo.c]"]
end

subgraph group_g_support["Support"]
  node_n_webclients["Web clients<br/>browser assets"]
  node_n_examples_server["Server examples<br/>sample apps"]
  node_n_examples_client["Client examples<br/>sample apps"]
  node_n_tests["Tests<br/>verification"]
  node_n_build["Build system<br/>build tooling<br/>[CMakeLists.txt]"]
end

node_n_include_rfb -->|"defines"| node_n_protocol
node_n_common -->|"uses"| node_n_sockets
node_n_common -->|"uses"| node_n_crypto
node_n_common -->|"uses"| node_n_compress
node_n_server -->|"contains"| node_n_server_session
node_n_server -->|"contains"| node_n_server_enc
node_n_server -->|"contains"| node_n_server_ws
node_n_server -->|"contains"| node_n_server_http
node_n_server -->|"contains"| node_n_server_ft
node_n_client -->|"contains"| node_n_client_conn
node_n_client -->|"contains"| node_n_client_dec
node_n_server_session -->|"uses"| node_n_common
node_n_server_enc -->|"uses"| node_n_common
node_n_client_conn -->|"uses"| node_n_common
node_n_client_dec -->|"uses"| node_n_common
node_n_server_session -->|"implements"| node_n_protocol
node_n_client_conn -->|"implements"| node_n_protocol
node_n_server_ws -->|"serves"| node_n_webclients
node_n_examples_server -->|"demonstrates"| node_n_server
node_n_examples_client -->|"demonstrates"| node_n_client
node_n_tests -->|"validates"| node_n_server
node_n_tests -->|"validates"| node_n_client
node_n_build -->|"builds"| node_n_server
node_n_build -->|"builds"| node_n_client
node_n_build -->|"builds"| node_n_common

click node_n_include_rfb "https://github.com/libvnc/libvncserver/tree/master/include/rfb"
click node_n_server "https://github.com/libvnc/libvncserver/tree/master/src/libvncserver"
click node_n_client "https://github.com/libvnc/libvncserver/tree/master/src/libvncclient"
click node_n_common "https://github.com/libvnc/libvncserver/tree/master/src/common"
click node_n_protocol "https://github.com/libvnc/libvncserver/blob/master/include/rfb/rfbproto.h"
click node_n_crypto "https://github.com/libvnc/libvncserver/blob/master/src/common/crypto.h"
click node_n_sockets "https://github.com/libvnc/libvncserver/blob/master/src/common/sockets.c"
click node_n_compress "https://github.com/libvnc/libvncserver/blob/master/src/common/minilzo.c"
click node_n_server_session "https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/rfbserver.c"
click node_n_server_enc "https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/zrle.c"
click node_n_server_ws "https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/websockets.c"
click node_n_server_http "https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/httpd.c"
click node_n_server_ft "https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/tightvnc-filetransfer/rfbtightserver.c"
click node_n_client_conn "https://github.com/libvnc/libvncserver/blob/master/src/libvncclient/rfbclient.c"
click node_n_client_dec "https://github.com/libvnc/libvncserver/blob/master/src/libvncclient/zrle.c"
click node_n_webclients "https://github.com/libvnc/libvncserver/tree/master/webclients"
click node_n_examples_server "https://github.com/libvnc/libvncserver/tree/master/examples/server"
click node_n_examples_client "https://github.com/libvnc/libvncserver/tree/master/examples/client"
click node_n_tests "https://github.com/libvnc/libvncserver/tree/master/test"
click node_n_build "https://github.com/libvnc/libvncserver/blob/master/CMakeLists.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_include_rfb toneBlue
class node_n_server,node_n_client,node_n_server_session,node_n_server_enc,node_n_server_ws,node_n_server_http,node_n_server_ft,node_n_client_conn,node_n_client_dec toneAmber
class node_n_common,node_n_protocol,node_n_crypto,node_n_sockets,node_n_compress toneMint
class node_n_webclients,node_n_examples_server,node_n_examples_client,node_n_tests,node_n_build toneRose
```

## Components

### Public API

Headers and contracts used by downstream embedders

- [Public headers](https://github.com/libvnc/libvncserver/tree/master/include/rfb): API surface · Primary embedded API under include/rfb for server and client consumers · `include/rfb`

### Runtime libs

Server and client protocol engines

- [libvncserver](https://github.com/libvnc/libvncserver/tree/master/src/libvncserver): VNC server lib · Server-side RFB session engine and framebuffer export pipeline · `src/libvncserver`
- [libvncclient](https://github.com/libvnc/libvncserver/tree/master/src/libvncclient): VNC client lib · Client-side RFB connection, decoding, and viewer pipeline · `src/libvncclient`
- [Server core](https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/rfbserver.c): session engine · Handshake, auth, framebuffer export, input handling, stats, and session coordination · `src/libvncserver/rfbserver.c`
- [Server encoders](https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/zrle.c): framebuffer encoders · Raw and compressed encodings used to send framebuffer updates · `src/libvncserver/zrle.c`
- [WebSocket path](https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/websockets.c): web transport · Browser-facing WebSocket handling and decoding for web delivery · `src/libvncserver/websockets.c`
- [HTTP bootstrap](https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/httpd.c): web support · Optional HTTP serving for launching the web client · `src/libvncserver/httpd.c`
- [File transfer](https://github.com/libvnc/libvncserver/blob/master/src/libvncserver/tightvnc-filetransfer/rfbtightserver.c): optional feature · TightVNC file transfer support layered on the server core · `src/libvncserver/tightvnc-filetransfer/rfbtightserver.c`
- [Client core](https://github.com/libvnc/libvncserver/blob/master/src/libvncclient/rfbclient.c): connection engine · Connection setup, listening/reverse connections, and client-side auth negotiation · `src/libvncclient/rfbclient.c`
- [Client decoders](https://github.com/libvnc/libvncserver/blob/master/src/libvncclient/zrle.c): framebuffer decoders · Raw and compressed encodings decoded into client-visible framebuffer updates · `src/libvncclient/zrle.c`

### Shared foundation

Code reused by both runtimes

- [Common code](https://github.com/libvnc/libvncserver/tree/master/src/common): shared infra · Reusable sockets, auth, crypto, compression, and utility helpers · `src/common`
- [RFB protocol](https://github.com/libvnc/libvncserver/blob/master/include/rfb/rfbproto.h): wire protocol · Shared protocol definitions and encoding contracts exposed through headers and implementation · `include/rfb/rfbproto.h`
- [Crypto backends](https://github.com/libvnc/libvncserver/blob/master/src/common/crypto.h): security layer · Pluggable OpenSSL, GnuTLS, libgcrypt, and built-in crypto support · `src/common/crypto.h`
- [Sockets](https://github.com/libvnc/libvncserver/blob/master/src/common/sockets.c): transport layer · TCP transport and socket helpers used by both runtimes · `src/common/sockets.c`
- [Compression](https://github.com/libvnc/libvncserver/blob/master/src/common/minilzo.c): encoding support · Base64, Zlib, LZO, TurboJPEG, and ZRLE-related helpers · `src/common/minilzo.c`

### Support

Examples, web assets, tests, and build tooling

- [Web clients](https://github.com/libvnc/libvncserver/tree/master/webclients): browser assets · Bundled noVNC viewer assets and browser bootstrap files · `webclients`
- [Server examples](https://github.com/libvnc/libvncserver/tree/master/examples/server): sample apps · Concrete embedding examples for framebuffer sources and server callbacks · `examples/server`
- [Client examples](https://github.com/libvnc/libvncserver/tree/master/examples/client): sample apps · Concrete viewer and tunneling examples for client embedding · `examples/client`
- [Tests](https://github.com/libvnc/libvncserver/tree/master/test): verification · Unit, integration, fuzz, and WebSocket-related validation coverage · `test`
- [Build system](https://github.com/libvnc/libvncserver/blob/master/CMakeLists.txt): build tooling · CMake, packaging metadata, and cross-compilation support · `CMakeLists.txt`

## Connections

- Public headers → RFB protocol: defines · Public headers define the protocol-facing API contracts
- Common code → Sockets: uses · Shared layer provides transport primitives
- Common code → Crypto backends: uses · Shared layer integrates pluggable security backends
- Common code → Compression: uses · Shared layer includes compression and utility helpers
- libvncserver → Server core: contains · Server library centers on session and framebuffer control
- libvncserver → Server encoders: contains · Server library includes encoding implementations
- libvncserver → WebSocket path: contains · Server library exposes WebSocket delivery path
- libvncserver → HTTP bootstrap: contains · Optional HTTP bootstrap support for web viewers
- libvncserver → File transfer: contains · Optional TightVNC file transfer extension
- libvncclient → Client core: contains · Client library manages connection and negotiation
- libvncclient → Client decoders: contains · Client library includes decoder pipeline
- Server core → Common code: uses · Server core depends on shared transport and crypto helpers
- Server encoders → Common code: uses · Server encoders rely on shared compression helpers
- Client core → Common code: uses · Client core depends on shared transport and security helpers
- Client decoders → Common code: uses · Client decoders rely on shared compression helpers
- Server core → RFB protocol: implements · Server side implements the RFB protocol behavior
- Client core → RFB protocol: implements · Client side implements the RFB protocol behavior
- WebSocket path → Web clients: serves · Server WebSocket path pairs with bundled browser assets
- Server examples → libvncserver: demonstrates · Examples show how to embed the server library
- Client examples → libvncclient: demonstrates · Examples show how to embed the client library
- Tests → libvncserver: validates · Tests cover server parsing, encodings, and transport behavior
- Tests → libvncclient: validates · Tests cover client decoding and connection behavior
- Build system → libvncserver: builds · Build system produces the server library
- Build system → libvncclient: builds · Build system produces the client library
- Build system → Common code: builds · Build system compiles shared support code