# bilibili/quiche architecture

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

- Interactive diagram: https://gitdiagram.com/bilibili/quiche
- Repository: https://github.com/bilibili/quiche

## Overview

##### Main Components
- Base Layer: Represent the “base” directory, which includes basic platform functions, logging (bvc-qlog), file utilities, POSIX wrappers, string utilities, etc.
- URL Processing: Mark “googleurl” as the module responsible for URL manipulation and related helper functions.
- QUIC & HTTP/3 Core: Represent “gquiche” (the integrated Google quiche source) as the heart of the QUIC protocol implementation.
- Networking and Platform Layers: Include “net” for low-level network functions and the various platform-specific implementations under “platform/…” (such as:
– platform/epoll_platform_impl (epoll-based I/O and event loop functionality),
– platform/http2_platform_impl (HTTP/2 stack implementation),
– platform/quic_platform_impl (adapter and implementation of QUIC-related functionalities),
– platform/quiche_platform_impl (further integration support for Google quiche),
– platform/spdy_platform_impl (supporting SPDY/HTTP2 features)).
- Third-Party Dependencies: Mark third-party libraries (in “third_party”) such as boringssl, abseil, rapidjson, etc.
- Utility Scripts / Tools: Use “utils” and parts of “gquiche” which contain sample server/client binaries (simple_quic_server, simple_quic_client) to illustrate how one can run this QUIC implementation in production.

##### Interactions and Relationships
- Application Examples ⇨ QUIC Core:
The simple_quic_server and simple_quic_client (built via cmake using the tools provided) sit atop the QUIC core. They are the entry points that utilize the underlying platform implementations.
- QUIC Core ⇨ Platform Abstractions:
The QUIC part (gquiche and components in platform/quic_platform_impl) interacts with the epoll (platform/epoll_platform_impl) and network (net) layers for I/O and event processing.
- QUIC Core ⇨ Cryptography and Logging:
The cryptographic operations, critical to QUIC’s TLS-like handshake and encryption, are handled through platform/quiche_platform_impl and third-party dependencies. Similarly, logging (Qlog) resides in the “base” layer.
- Supporting Libraries:
googleurl provides URL parsing and related services used by the client and server, while “base” also supplies file and string utilities that are widely used across the project.
- External Dependencies:
These include the support libraries from “third_party” (like boringssl) that provide underlying cryptographic and utility functions.

##### Architectural Patterns and Design Principles
- Modular layering: The project is clearly separated into low-level utility and OS adaptation (base, net), protocol and core implementation (gquiche, quic_platform_impl), and frontend interfaces (client/server examples).
- Loose coupling, where each “platform” layer abstracts away OS-dependent code.
- Clear separation of concerns: Each directory (base, googleurl, gquiche, platform/*, third_party, utils) corresponds to a different functional aspect of the QUIC implementation.
- Extensibility: The architecture supports easy upgrading of Google quiche, with separate modules for platform-specific changes, making it easier to integrate changes from the upstream project.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Layer
    subgraph "Application Layer"
        T1["Utils: Utility Scripts"]:::app
        T2["QUIC Tools: Sample Server/Client"]:::app
    end

    %% QUIC Core
    subgraph "QUIC Core"
        G["gquiche: Core QUIC Protocol"]:::core
    end

    %% Platform Abstractions
    subgraph "Platform Abstractions"
        P1["platform/quic_platform_impl: QUIC functionalities"]:::platform
        P2["platform/quiche_platform_impl: Google quiche integration"]:::platform
        P3["platform/epoll_platform_impl: Epoll-based I/O"]:::platform
        P4["platform/http2_platform_impl: HTTP2 Implementation"]:::platform
        P5["platform/spdy_platform_impl: SPDY/HTTP2 Support"]:::platform
    end

    %% Support Layer
    subgraph "Support Layer"
        B["Base: Qlog, Files, Posix, Strings, Sinks"]:::support
        GURL["googleurl: URL Parsing"]:::support
        N["net: Network I/O"]:::support
        TP["third_party: Dependencies (boringssl, abseil, rapidjson)"]:::support
    end

    %% Connections from Application Layer to QUIC Core
    T1 -->|"uses"| G
    T2 -->|"uses"| G

    %% QUIC Core interactions
    G -->|"calls"| P1
    G -->|"integrates"| P2
    G -->|"handles_I/O"| N
    G -->|"utilizes"| B
    G -->|"parses"| GURL

    %% Platform Abstractions connections
    P1 -->|"employs_I/O"| P3
    P1 -->|"triggers_events"| N
    P2 -->|"crypto_logging"| TP

    %% Application Layer additional dependencies on Support Layer
    T1 -->|"uses_utilities"| B
    T1 -->|"uses_URL"| GURL
    T2 -->|"parses_URL"| GURL

    %% Styles
    classDef app fill:#fceabb,stroke:#d18c00,stroke-width:2px;
    classDef core fill:#9fd6e3,stroke:#2a9d8f,stroke-width:2px;
    classDef platform fill:#f5c6aa,stroke:#e76f51,stroke-width:2px;
    classDef support fill:#d0e1d4,stroke:#264653,stroke-width:2px;

    %% Click Events
    click B "https://github.com/bilibili/quiche/tree/main/base"
    click GURL "https://github.com/bilibili/quiche/tree/main/googleurl"
    click G "https://github.com/bilibili/quiche/tree/main/gquiche"
    click N "https://github.com/bilibili/quiche/tree/main/net"
    click TP "https://github.com/bilibili/quiche/tree/main/third_party"
    click P1 "https://github.com/bilibili/quiche/tree/main/platform/quic_platform_impl"
    click P2 "https://github.com/bilibili/quiche/tree/main/platform/quiche_platform_impl"
    click P3 "https://github.com/bilibili/quiche/tree/main/platform/epoll_platform_impl"
    click P4 "https://github.com/bilibili/quiche/tree/main/platform/http2_platform_impl"
    click P5 "https://github.com/bilibili/quiche/tree/main/platform/spdy_platform_impl"
    click T1 "https://github.com/bilibili/quiche/tree/main/utils"
    click T2 "https://github.com/bilibili/quiche/tree/main/gquiche/quic/tools"
```
