# warmcat/libwebsockets architecture

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

- Interactive diagram: https://gitdiagram.com/warmcat/libwebsockets
- Repository: https://github.com/warmcat/libwebsockets

## Overview

##### Main Components
a. Core Engine & Context Management – Represent the base “lib/core” and “lib/system” components that implement connection state, event handling, and resource management.
b. Protocol Implementations – Include distinct modules for HTTP (roles/h1, roles/h2, roles/http), WebSockets (roles/ws), MQTT (roles/mqtt) and other protocol-specific logic.
c. Secure Streams (SS) Layer – A higher-level abstraction sitting on top of the raw connections, defined in the “lib/secure-streams” section. Also include serialized secure streams and the SS Proxy component (ssproxy) to show how it abstractly manages policy, retries, and multiplexing.
d. TLS & Crypto Abstraction – Show the “lib/tls” subsystem which supports various TLS providers (OpenSSL, MbedTLS, etc.) and the cryptographic modules (e.g., in lib/cose, lib/jose) that work with crypto protocols.
g. Policy & Configuration – Emphasize the JSON-based “policy” portion that drives, for example, the vhost, secure streams settings, TLS validation details, connection retry/backoff, and protocol negotiation. This is key in the SS layer where endpoint, protocol, and metadata information are centralized.
h. Sample Applications and Plugins – Represent how minimal examples (in minimal-examples, test-apps) and plugins (both standalone and in the “plugins” folder) use the library. Indicate that these serve as both integration tests and “client/server” demonstrations.

##### Relationships and Interactions
- Secure streams layer as connecting upward from the low-level wsi APIs. Emphasize that policy JSON input drives SS behavior on top of the core connection management.
- How the event loops feed events into the core processing, and that TLS (and crypto) modules attach to every connection for security handling.

##### Design Patterns and Patterns to Highlight
- Modular design: the project is built in logical “modules” (or libraries) that can be independently built and configured using CMake.
- Separation of concerns: from low-level connection handling (wsi) to higher-level secure streams abstraction – with policy files governing behavior.
- Event-driven architecture: multiple event loop integrations are supported; display a central “event scheduler” receiving I/O events and dispatching them to protocol handlers.
- Configurability through JSON: show that many parameters (connection endpoints, TLS settings, retry policies) are externalized into policy files for both runtime adaptation and easy configuration.
- Portability: illustrate separate branches for platform-specific implementations, such as within lib/plat for UNIX, Windows, FreeRTOS, etc.

##### Technologies, Frameworks, and Tools
- CMake is used for building across platforms.
- Multiple crypto libraries (MbedTLS, OpenSSL) as indicated in lib/tls.
- Several event loop libraries (libuv, libev, glib, etc.) and plugins provide integration.

##### Extra Detail
- Subcomponents from directories such as “lib/drivers” (button, led, netdev, etc.) and “lib/event-libs” (showing different supported event libraries).
- That testing (CI and test-apps) and auxiliary scripts (in scripts/) support the development and build process but are not part of the runtime architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top Layer
    PolicyConfig("Policy & Config"):::policy

    %% Secure Streams Layer
    SecureStreams("Secure Streams"):::secure

    %% Core Engine Subgraph
    subgraph "Core Engine"
        CoreLib("Core Library"):::core
        SystemMgmt("System Management"):::core
    end

    %% Protocol Implementations
    HTTP1("HTTP/1"):::protocol
    HTTP2("HTTP/2"):::protocol
    HTTPGeneral("HTTP"):::protocol
    WebSockets("WebSockets"):::protocol
    MQTT("MQTT"):::protocol

    %% TLS & Crypto Abstraction
    TLS("TLS"):::crypto
    COSE("COSE"):::crypto
    JOSE("JOSE"):::crypto

    %% Event Loop Integration
    EventLoop("Event Loops"):::event

    %% Platform & Driver Abstraction
    PlatformAbstraction("Platform Abstraction"):::platform
    Drivers("Drivers"):::platform

    %% Sample Applications and Plugins
    Samples("Samples"):::sample
    Plugins("Plugins"):::sample
    StandalonePlugin("Standalone Plugin"):::sample

    %% Relationships
    PolicyConfig -->|"feeds"| SecureStreams
    SecureStreams -->|"integrates"| CoreLib

    EventLoop -->|"triggers"| CoreLib
    TLS -->|"secures"| CoreLib
    COSE -->|"secures"| CoreLib
    JOSE -->|"secures"| CoreLib
    PlatformAbstraction -->|"supports"| CoreLib
    Drivers -->|"supports"| CoreLib

    HTTP1 -->|"utilizes"| CoreLib
    HTTP2 -->|"utilizes"| CoreLib
    HTTPGeneral -->|"utilizes"| CoreLib
    WebSockets -->|"utilizes"| CoreLib
    MQTT -->|"utilizes"| CoreLib

    Samples -->|"interacts"| CoreLib
    Plugins -->|"interacts"| CoreLib
    StandalonePlugin -->|"interacts"| CoreLib

    %% Click Events for Core Engine & Context Management
    click CoreLib "https://github.com/warmcat/libwebsockets/tree/main/lib/core"
    click SystemMgmt "https://github.com/warmcat/libwebsockets/tree/main/lib/system"

    %% Click Events for Protocol Implementations
    click HTTP1 "https://github.com/warmcat/libwebsockets/tree/main/lib/roles/h1"
    click HTTP2 "https://github.com/warmcat/libwebsockets/tree/main/lib/roles/h2"
    click HTTPGeneral "https://github.com/warmcat/libwebsockets/tree/main/lib/roles/http"
    click WebSockets "https://github.com/warmcat/libwebsockets/tree/main/lib/roles/ws"
    click MQTT "https://github.com/warmcat/libwebsockets/tree/main/lib/roles/mqtt"

    %% Click Event for Secure Streams Layer
    click SecureStreams "https://github.com/warmcat/libwebsockets/tree/main/lib/secure-streams"

    %% Click Events for TLS & Crypto Abstraction
    click TLS "https://github.com/warmcat/libwebsockets/tree/main/lib/tls"
    click COSE "https://github.com/warmcat/libwebsockets/tree/main/lib/cose"
    click JOSE "https://github.com/warmcat/libwebsockets/tree/main/lib/jose"

    %% Click Event for Event Loop Integration
    click EventLoop "https://github.com/warmcat/libwebsockets/tree/main/lib/event-libs"

    %% Click Events for Platform & Driver Abstraction
    click PlatformAbstraction "https://github.com/warmcat/libwebsockets/tree/main/lib/plat"
    click Drivers "https://github.com/warmcat/libwebsockets/tree/main/lib/drivers"

    %% Click Events for Policy & Configuration
    click PolicyConfig "https://github.com/warmcat/libwebsockets/tree/main/lib/secure-streams"

    %% Click Events for Sample Applications and Plugins
    click Samples "https://github.com/warmcat/libwebsockets/tree/main/minimal-examples"
    click Plugins "https://github.com/warmcat/libwebsockets/tree/main/plugins"
    click StandalonePlugin "https://github.com/warmcat/libwebsockets/tree/main/plugin-standalone"

    %% Styles
    classDef core fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef protocol fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef secure fill:#a9dfbf,stroke:#28b463,stroke-width:2px;
    classDef crypto fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef event fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef platform fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef policy fill:#f9c984,stroke:#d35400,stroke-width:2px;
    classDef sample fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
```
