# ithewei/libhv architecture

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

- Interactive diagram: https://gitdiagram.com/ithewei/libhv
- Repository: https://github.com/ithewei/libhv

## Overview

##### Project Type and Purpose
- libhv is a cross-platform, high-performance networking library written in C/C++.
- It exposes an event-driven API (event loop, non-blocking IO, timers) and layered protocol support (TCP/UDP, HTTP/1.x & HTTP/2, WebSocket, MQTT, RUDP/KCP, SSL/TLS).
- It is intended as an embeddable middleware for building servers, clients, and proxies in C/C++.

##### File-Structure Analysis
- Top-level build and config: BUILD.bazel, CMakeLists.txt, Makefile, scripts/, etc.
- Core library modules:
- base/: low-level abstractions (threading, atomics, socket wrappers, logging, memory, queues)
- event/: event loop implementation and IO pollers (epoll, kqueue, iocp, select, custom watches)
- http/: HTTP protocol stack (parsers, client, server, routers, middleware)
- ssl/: pluggable SSL/TLS back-ends
- protocol/: other protocols (DNS, FTP, SMTP, ICMP)
- mqtt/: MQTT client
- util/: helper algorithms (base64, MD5, SHA1)
- Example layers: evpp/ (C++ wrapper/API), examples/, echo-servers/, unittest/, docs/, html/

##### Architectural Components
- OS Abstraction Layer
- System calls, thread, mutex, atomics, time – implemented in base/ and hplatform.h
- Event Loop Core
- hv::EventLoop, pollers (epoll, kqueue, iocp) – event/hloop.*
- Non-Blocking IO Layer
- SocketChannel, watchers – event/hsocket.*, event/iowatcher.h
- Protocol Modules (layered on top of IO)
- TCP/UDP client & server – base socket wrappers, event loop
- HTTP stack – parsers (Http1Parser, Http2Parser), HttpServer, HttpClient, middleware
- WebSocket – framing, channels
- MQTT – packet parser, client
- RUDP (KCP) – ikcp integration
- Other protocols (DNS, FTP, SMTP)
- SSL/TLS Pluggable Backend
- Openssl, GnuTLS, mbedtls adapters under ssl/
- C++ Wrappers (evpp/)
- Clean C++ classes: Channel, EventLoop, TcpServer, HttpService
- Application-Facing API
- exposed headers (hv.h, hv_http.h, hv_ssl.h, etc.)
- Build & Deployment
- CMake, Bazel, Make, vcpkg/xrepo

##### Relationships & Data Flows
- Protocol modules invoking callbacks into user code.
- How SSL wraps socket channels transparently.
- C++ evpp wrappers calling the C core.

##### Architectural Patterns & Principles
- Layered Architecture: separation of concerns from OS to high-level API.
- Event-Driven Callback Pattern: non-blocking IO dispatch, user registers onConnection/onMessage handlers.
- Adapter Pattern: SSL back-ends; KCP integration.
- Modular Design: each protocol module sits in its own directory, with clear public headers.

## Diagram (Mermaid)

```mermaid
graph TB
    %% OS Abstraction Layer
    subgraph "OS Abstraction Layer"
        OSAbs["OS Abstraction"]:::osAbstraction
    end

    %% Event Loop & IO Layer
    subgraph "Event Loop & IO Layer"
        EventLoopCore["EventLoop Core\n(hloop.*, hevent.*)"]:::event
        Pollers["Pollers\n(epoll, kqueue, iocp, select, etc.)"]:::event
        SocketChannel["SocketChannel & Watchers"]:::io
    end

    %% Protocol Modules
    subgraph "Protocol Modules"
        HTTP["HTTP Protocol Module"]:::protocol
        WebSocket["WebSocket Service"]:::protocol
        MQTT["MQTT Module"]:::protocol
        OtherProto["Other Protocols\n(DNS, FTP, SMTP, ICMP)"]:::protocol
        KCP["RUDP/KCP Integration"]:::protocol
    end

    %% SSL Adapter
    subgraph "SSL/TLS Adapter"
        SSL["SSL Adapter\n(OpenSSL, GnuTLS, mbedtls, etc.)"]:::ssl
    end

    %% Application API & Wrappers
    subgraph "API & Wrappers"
        CAPI["C API Headers\n(hv.h, hexport.h, hconfig.h)"]:::api
        CPPWrapper["C++ Wrapper (evpp)"]:::wrapper
    end

    %% Examples
    subgraph "Examples & Tools"
        Examples["Examples & Tests"]:::examples
        BuildTools["Build & Deployment\n(CMake, Bazel, Make, scripts/)"]:::examples
    end

    %% Dependencies and Data Flows
    OSAbs -->|"syscalls, threads, atomics"| EventLoopCore
    EventLoopCore -->|"schedules events"| Pollers
    Pollers -->|"watches FDs"| SocketChannel
    SocketChannel -->|"raw IO"| HTTP
    SocketChannel -->|"raw IO"| MQTT
    SocketChannel -->|"raw IO"| OtherProto
    SocketChannel -->|"raw IO"| KCP
    HTTP -->|"parsing & routing"| WebSocket
    KCP -->|"wraps UDP"| SocketChannel
    SSL -. wraps .-> SocketChannel
    HTTP -->|"exposed via"| CAPI
    MQTT -->|"exposed via"| CAPI
    OtherProto -->|"exposed via"| CAPI
    KCP -->|"exposed via"| CAPI
    CAPI -->|"C core API"| CPPWrapper
    CPPWrapper -->|"calls C core"| EventLoopCore
    Examples -->|"use API"| CAPI
    Examples -->|"use Wrapper"| CPPWrapper
    BuildTools -->|"build system"| CAPI

    %% Click Events
    click OSAbs "https://github.com/ithewei/libhv/tree/master/base/"
    click EventLoopCore "https://github.com/ithewei/libhv/tree/master/event/"
    click Pollers "https://github.com/ithewei/libhv/blob/master/event/epoll.c"
    click SocketChannel "https://github.com/ithewei/libhv/blob/master/event/iowatcher.h"
    click HTTP "https://github.com/ithewei/libhv/tree/master/http/"
    click WebSocket "https://github.com/ithewei/libhv/blob/master/http/server/WebSocketServer.h"
    click MQTT "https://github.com/ithewei/libhv/tree/master/mqtt/"
    click OtherProto "https://github.com/ithewei/libhv/tree/master/protocol/"
    click KCP "https://github.com/ithewei/libhv/blob/master/event/kcp/hkcp.c"
    click SSL "https://github.com/ithewei/libhv/tree/master/ssl/"
    click CPPWrapper "https://github.com/ithewei/libhv/blob/master/evpp/Channel.h"
    click CAPI "https://github.com/ithewei/libhv/blob/master/hv.h"
    click BuildTools "https://github.com/ithewei/libhv/tree/master/scripts/"

    %% Styles
    classDef osAbstraction fill:#f9f,stroke:#333,stroke-width:1px
    classDef event fill:#9ff,stroke:#333,stroke-width:1px
    classDef io fill:#ff9,stroke:#333,stroke-width:1px
    classDef protocol fill:#9f9,stroke:#333,stroke-width:1px
    classDef ssl fill:#fc9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef api fill:#ccf,stroke:#333,stroke-width:1px
    classDef wrapper fill:#cfc,stroke:#333,stroke-width:1px
    classDef examples fill:#fcc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
