# google/quiche architecture

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

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

## Overview

##### Main components
- Build Infrastructure & Tooling: At the top level, show Bazel files (BUILD.bazel, MODULE.bazel, etc.) and the “depstool” (written in Go) responsible for dependency management.
– QUIC: Representing quiche/quic, which contains sub-components for connection management, congestion control, crypto (with many crypto submodules), frames, packet processing, stream management, etc.
– HTTP/3 & WebTransport: Show quiche/web_transport and web_transport/encapsulated, which extend the protocol support into HTTP/3 and WebTransport.
- Platform Abstraction Layer: Create a segment for quiche/common/platform and quiche/quic/platform where platform APIs are defined. Emphasize that “default” implementations exist (e.g., under quiche/common/platform/default) and that embedders can replace these with their own.
- Additional Protocol Extensions: Identify other components such as:
– quiche/balsa for header processing,
– quiche/binary_http and quiche/blind_sign_auth for specialized messaging and authentication.
- Testing and Simulation: The project contains extensive test tools and simulators (under quiche/test_tools and quiche/quic/test_tools/simulator) to validate individual modules and integrated behavior.
- Integrations & External Service Interfaces: Document how QUICHE is integrated into larger systems (Chromium, Envoy). Although not directly visible in the file tree, include an “Integration Points” section that references platform implementations and build file adaptations.

##### Relationships and interactions
– The core QUIC modules rely on crypto, congestion control, and packet processing libraries from QUIC.
– HTTP/2 components build on lower‑level utilities (like hpack, HTTP header processing) and interoperate with QUIC to form HTTP/3.
– Platform API abstractions (in common/platform) interact with both QUIC and HTTP/2 implementations in order to allow embedding in different environments.
- “test tools” as supporting and validating each module. Indicate that each library module has associated test folders that simulate or stress test interactions.

##### Important architectural patterns and design principles
- Modularization: Each protocol and utility is encapsulated in its own directory and can be seen as a module. Illustrate how these modules communicate via well-defined interfaces.
- Layered Architecture: From low-level packet routing and crypto (in QUIC’s “core/crypto” modules) up to high-level HTTP/2 and WebTransport interfaces.
- Platform Abstraction: Emphasize the split between platform-independent logic and platform-specific implementations provided in default directories. Note the forward-thinking design for custom embedding.
- Extensive Testing & Simulation: Capture the emphasis on unit tests, simulators, and fuzzer/test tools that validate protocol robustness.

##### Relevant technologies and frameworks
- Bazel Build System: Mark components that use Bazel (BUILD.bazel, MODULE.bazel, etc.) for construction and dependency management.
- Go-based Depstool: Mention the tool (depstool) used for dependency automation.
- C++ is the primary language for protocol implementations and tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Infrastructure & Tooling
    subgraph "Build Infrastructure & Tooling"
        BAZEL["Bazel Files"]:::build
        DEPSTOOL["Depstool"]:::build
    end

    %% Core Protocol Libraries
    subgraph "Core Protocol Libraries"
        subgraph "QUIC"
            QUIC["QUIC"]:::protocol
            QUIC_CRYPTO["Crypto"]:::protocolInner
            QUIC_CONG["Congestion_Control"]:::protocolInner
            QUIC_FRAMES["Frames_Packets"]:::protocolInner
            QUIC_STREAM["Stream_Management"]:::protocolInner
        end
        subgraph "HTTP/2"
            HTTP2["HTTP/2"]:::protocol
            HTTP2_ADAPTER["Adapter"]:::protocolInner
            HTTP2_CORE["Core"]:::protocolInner
            HTTP2_DECODER["Decoder"]:::protocolInner
            HTTP2_HPACK["HPACK"]:::protocolInner
        end
        subgraph "HTTP/3 & WebTransport"
            HTTP3["HTTP/3 & WebTransport"]:::protocol
            HTTP3_ENCAP["Encapsulated"]:::protocolInner
        end
    end

    %% Supporting Utilities and Common Libraries
    subgraph "Supporting Utilities and Common Libraries"
        COMMON["Common Modules"]:::common
    end

    %% Platform Abstraction Layer
    subgraph "Platform Abstraction Layer"
        PLATFORM_COMMON["Platform Common"]:::platform
        PLATFORM_QUIC["Platform QUIC"]:::platform
    end

    %% Additional Protocol Extensions
    subgraph "Additional Protocol Extensions"
        BALSA["Header_Processing"]:::extension
        BINARY_HTTP["Binary_HTTP"]:::extension
        BLIND_SIGN["Blind_Sign_Auth"]:::extension
    end

    %% Testing and Simulation
    subgraph "Testing and Simulation"
        TEST_QUIC["QUIC Test Simulator"]:::test
        TEST_HTTP2["HTTP/2 Test Tools"]:::test
        TEST_COMMON["Common Test Tools"]:::test
    end

    %% Integrations & External Service Interfaces
    subgraph "Integrations & External Service Interfaces"
        INTEGRATION["Integration Points"]:::integration
    end

    %% Connections between Build Infrastructure and Modules
    DEPSTOOL --> BAZEL
    BAZEL --> QUIC
    BAZEL --> HTTP2
    BAZEL --> HTTP3
    BAZEL --> COMMON
    BAZEL --> PLATFORM_COMMON
    BAZEL --> PLATFORM_QUIC
    BAZEL --> BALSA
    BAZEL --> BINARY_HTTP
    BAZEL --> BLIND_SIGN
    BAZEL --> TEST_QUIC
    BAZEL --> TEST_HTTP2
    BAZEL --> TEST_COMMON

    %% Internal QUIC Module Connections
    QUIC_CRYPTO --> QUIC
    QUIC_CONG --> QUIC
    QUIC_FRAMES --> QUIC
    QUIC_STREAM --> QUIC

    %% Internal HTTP/2 Module Connections
    HTTP2_ADAPTER --> HTTP2
    HTTP2_CORE --> HTTP2
    HTTP2_DECODER --> HTTP2
    HTTP2_HPACK --> HTTP2
    HTTP2_HPACK -->|uses| HTTP2_DECODER

    %% Internal HTTP/3 & WebTransport Connections
    HTTP3_ENCAP --> HTTP3

    %% Common Modules support for Protocol Libraries
    QUIC --> COMMON
    HTTP2 --> COMMON
    HTTP3 --> COMMON

    %% Platform Abstraction to Protocol Libraries
    PLATFORM_COMMON --> QUIC
    PLATFORM_COMMON --> HTTP2
    PLATFORM_QUIC --> QUIC

    %% Testing links to Modules
    TEST_QUIC --> QUIC
    TEST_HTTP2 --> HTTP2
    TEST_COMMON --> COMMON

    %% Integration Points connections
    QUIC --> INTEGRATION
    HTTP2 --> INTEGRATION
    HTTP3 --> INTEGRATION
    PLATFORM_COMMON --> INTEGRATION
    PLATFORM_QUIC --> INTEGRATION

    %% Protocol Interoperation
    HTTP2 --> HTTP3

    %% Styles
    classDef build fill:#FFCC00,stroke:#333,stroke-width:2px,color:#000;
    classDef protocol fill:#A1D490,stroke:#333,stroke-width:2px,color:#000;
    classDef protocolInner fill:#DFF0D8,stroke:#333,stroke-width:1px,color:#000;
    classDef common fill:#ADD8E6,stroke:#333,stroke-width:2px,color:#000;
    classDef platform fill:#F7A1A1,stroke:#333,stroke-width:2px,color:#000;
    classDef extension fill:#E6CCFF,stroke:#333,stroke-width:2px,color:#000;
    classDef test fill:#FFF2CC,stroke:#333,stroke-width:2px,color:#000;
    classDef integration fill:#C0C0C0,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events
    click BAZEL "https://github.com/google/quiche/blob/main/BUILD.bazel"
    click DEPSTOOL "https://github.com/google/quiche/tree/main/depstool"
    click QUIC "https://github.com/google/quiche/tree/main/quiche/quic"
    click HTTP2 "https://github.com/google/quiche/tree/main/quiche/http2"
    click HTTP3 "https://github.com/google/quiche/tree/main/quiche/web_transport"
    click HTTP3_ENCAP "https://github.com/google/quiche/tree/main/quiche/web_transport/encapsulated"
    click COMMON "https://github.com/google/quiche/tree/main/quiche/common"
    click PLATFORM_COMMON "https://github.com/google/quiche/tree/main/quiche/common/platform"
    click PLATFORM_QUIC "https://github.com/google/quiche/tree/main/quiche/quic/platform"
    click BALSA "https://github.com/google/quiche/tree/main/quiche/balsa"
    click BINARY_HTTP "https://github.com/google/quiche/tree/main/quiche/binary_http"
    click BLIND_SIGN "https://github.com/google/quiche/tree/main/quiche/blind_sign_auth"
    click TEST_QUIC "https://github.com/google/quiche/tree/main/quiche/quic/test_tools/simulator"
    click TEST_HTTP2 "https://github.com/google/quiche/tree/main/quiche/http2/test_tools"
    click TEST_COMMON "https://github.com/google/quiche/tree/main/quiche/common/test_tools"
```
