# unetworking/uwebsockets architecture

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

- Interactive diagram: https://gitdiagram.com/unetworking/uwebsockets
- Repository: https://github.com/unetworking/uwebsockets

## Overview

##### Project type and purpose
- µWebSockets is a high-performance, embeddable C/C++ library that implements a standards-compliant HTTP/WebSocket server.
- It sits on top of µSockets (eventing, networking, crypto) and offers a simple URL router, pub/sub for WebSockets, and Node.js bindings.
- The repository contains the core library (src/), examples (examples/), benchmarks (benchmarks/), fuzz tests (fuzzing/), spec tests (autobahn/, h1spec/), and CI workflows.

##### File structure
- Top-level modules:
- src/ – core C++ headers, classes and protocol implementations (App, HttpParser, WebSocket, Router, etc.)
- uSockets/ – the submodule implementing raw event loops (epoll/kqueue), networking and crypto layers (OpenSSL/WolfSSL)
- examples/ – sample applications showing how to wire routes and WebSocket handlers
- benchmarks/ – performance tests driving design decisions
- fuzzing/ – harnesses for daily OSS-Fuzz coverage on parsers, extensions, topic trees, etc.
- tests/ – unit and smoke tests validating individual components
- cluster/ – helper for running one app instance per CPU core
- build files – Makefile, GNUmakefile, build.{c,h}, .github/workflows

##### README for additional insights
- The README emphasizes a layered architecture:
- µWebSockets (HTTP, WebSocket, Router, Pub/Sub)
- µSockets (event loop, socket I/O, TLS/crypto)
- Flexible build flags for SSL backends (OpenSSL/WolfSSL) and event‐loop integrations (libuv, ASIO, GCD, raw epoll/kqueue)
- It calls out Autobahn compliance, OSS-Fuzz integration, and benchmark-driven development.

a. Main components
1. External Clients (HTTP browsers, WebSocket clients, Node.js scripts)
2. Networking & Crypto Layer (µSockets)
– Event loop implementations (raw epoll/kqueue, libuv, ASIO, GCD)
– TLS backends (OpenSSL, WolfSSL)
3. µWebSockets Core (src/)
– App/SSLApp orchestration
– HTTP layer: HttpParser, ChunkedEncoding, HttpContext, Router
– WebSocket layer: WebSocketHandshake, WebSocketProtocol, Extensions, Pub/Sub (TopicTree)
4. Application Layer (user callbacks)
– Route handlers (.get, .post)
– WebSocket event handlers (open, message, close)
5. Tooling & Testing
– Examples harness (examples/)
– Benchmarks (benchmarks/)
– Fuzzing suite (fuzzing/)
– Spec tests (autobahn/, h1spec/)
– CI/CD pipelines (.github/workflows/)
b. Relationships & interactions
- Build-time feature flags branching the Networking layer to different event loops or TLS backends.
- Flow inside the core: raw bytes → HttpParser → Router → user callback → HttpResponseData → write to socket.
- For WebSockets: handshake → protocol framing → Extensions → Pub/Sub subscription → message dispatch.
c. Architectural patterns & design principles
- Layered architecture with clear separation of concerns (I/O, protocol parsing, routing, application logic).
- Plugin-style extensibility via template parameters and build flags.
- One-app-per-thread model with shared listening socket for multi-core scaling.
- Test harnesses to ensure protocol compliance (fuzzing, spec tests) and performance (benchmarks).
d. Key technologies & libraries
- C/C++17 (headers in src/)
- µSockets submodule (C) with TLS options (OpenSSL/WolfSSL)
- Autobahn Testsuite, OSS-Fuzz, libdeflate for compression
- Make/GNUmake build system, GitHub Actions for CI

##### Detail without over-complication
- Build flags and CI steps alongside the relevant layers.
- How examples, benchmarks, fuzzing and tests hook into the core library for validation, compliance, and performance measurement.
- You convey both runtime behavior (request handling) and build-time configurability (flag-driven module inclusion).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    ExternalClients(("External Clients")):::external

    %% Networking & Crypto Layer
    subgraph "Networking & Crypto Layer" 
        direction TB
        USockets["µSockets\n- Event Loops: epoll/kqueue, libuv, ASIO, GCD\n- TLS: OpenSSL, WolfSSL"]:::network
    end

    %% Build Config & Flags
    BuildConfig["Build Config & Flags\n(build.c, build.h, GNUmakefile, Makefile)"]:::network
     
    %% µWebSockets Core
    subgraph "µWebSockets Core (src/)" 
        direction TB
        AppH["App.h"]:::core
        ClientAppH["ClientApp.h"]:::core
        subgraph "HTTP Engine"
            direction TB
            HttpParserH["HttpParser.h"]:::core
            HttpRouterH["HttpRouter.h"]:::core
        end
        subgraph "WebSocket Engine"
            direction TB
            WebSocketHandshakeH["WebSocketHandshake.h"]:::core
            WebSocketProtocolH["WebSocketProtocol.h"]:::core
            WebSocketH["WebSocket.h"]:::core
            subgraph "Extensions & Pub/Sub"
                direction TB
                TopicTreeH[(TopicTree.h)]:::core
            end
        end
    end

    %% Application Layer
    subgraph "Application Layer (examples/)"
        direction TB
        Examples["User Callbacks & Examples"]:::app
    end

    %% Tooling & Testing
    subgraph "Tooling & Testing"
        direction TB
        Benchmarks["Benchmarks Suite"]:::tooling
        Fuzzing["Fuzzing Suite"]:::tooling
        subgraph "Spec Compliance Tests"
            direction TB
            Autobahn["Autobahn Tests"]:::tooling
            H1Spec["HTTP/1 Spec Tests"]:::tooling
        end
        UnitTests["Unit & Smoke Tests"]:::tooling
        ClusterHelper["Cluster Helper"]:::tooling
        CICD["CI/CD Workflows"]:::tooling
    end

    %% Data Flow
    ExternalClients -->|"TCP/TLS"| USockets
    BuildConfig -.-> USockets
    BuildConfig -.-> AppH
    USockets -->|"raw bytes"| HttpParserH
    HttpParserH -->|"parsed req"| HttpRouterH
    HttpRouterH -->|"route handler"| Examples
    Examples -->|"HttpResponseData"| AppH
    AppH -->|"write to socket"| USockets
    HttpParserH --> WebSocketHandshakeH
    WebSocketHandshakeH --> WebSocketProtocolH
    WebSocketProtocolH --> TopicTreeH
    TopicTreeH --> Examples
    Examples -->|"pub/sub msg"| TopicTreeH

    %% Tooling Hooks
    Benchmarks --> USockets
    Benchmarks --> HttpParserH
    Fuzzing --> HttpParserH
    Fuzzing --> TopicTreeH
    Fuzzing --> WebSocketH
    Autobahn --> WebSocketProtocolH
    H1Spec --> HttpParserH
    UnitTests --> HttpParserH
    UnitTests --> HttpRouterH
    UnitTests --> TopicTreeH
    ClusterHelper --> USockets
    CICD --> Benchmarks
    CICD --> Fuzzing
    CICD --> UnitTests

    %% Click Events
    click USockets "https://github.com/unetworking/uwebsockets/tree/master/uSockets/"
    click BuildConfig "https://github.com/unetworking/uwebsockets/blob/master/build.c"
    click AppH "https://github.com/unetworking/uwebsockets/blob/master/src/App.h"
    click ClientAppH "https://github.com/unetworking/uwebsockets/blob/master/src/ClientApp.h"
    click HttpParserH "https://github.com/unetworking/uwebsockets/blob/master/src/HttpParser.h"
    click HttpRouterH "https://github.com/unetworking/uwebsockets/blob/master/src/HttpRouter.h"
    click WebSocketH "https://github.com/unetworking/uwebsockets/blob/master/src/WebSocket.h"
    click TopicTreeH "https://github.com/unetworking/uwebsockets/blob/master/src/TopicTree.h"
    click WebSocketHandshakeH "https://github.com/unetworking/uwebsockets/blob/master/src/WebSocketHandshake.h"
    click WebSocketProtocolH "https://github.com/unetworking/uwebsockets/blob/master/src/WebSocketProtocol.h"
    click Examples "https://github.com/unetworking/uwebsockets/tree/master/examples/"
    click Benchmarks "https://github.com/unetworking/uwebsockets/tree/master/benchmarks/"
    click Fuzzing "https://github.com/unetworking/uwebsockets/tree/master/fuzzing/"
    click Autobahn "https://github.com/unetworking/uwebsockets/tree/master/autobahn/"
    click H1Spec "https://github.com/unetworking/uwebsockets/tree/master/h1spec/"
    click UnitTests "https://github.com/unetworking/uwebsockets/tree/master/tests/"
    click ClusterHelper "https://github.com/unetworking/uwebsockets/tree/master/cluster/"
    click CICD "https://github.com/unetworking/uwebsockets/blob/master/.github/workflows/cpp.yml"

    %% Styles
    classDef external fill:#D6EFFF,stroke:#0066CC,color:#0066CC
    classDef network fill:#D6F5D6,stroke:#339933,color:#005500
    classDef core fill:#E8F1FF,stroke:#3366CC,color:#003399
    classDef app fill:#FFF5CC,stroke:#CCA300,color:#806600
    classDef tooling fill:#F2F2F2,stroke:#999999,color:#666666
```
