# quicr/libquicr architecture

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

- Interactive diagram: https://gitdiagram.com/quicr/libquicr
- Repository: https://github.com/quicr/libquicr

## Overview

##### Project type and purpose
- libquicr is a C++ API library implementing a publish/subscribe protocol (draft-ietf-moq-transport-04).
- It provides both client-side and server-side (relay) APIs, plus example executables (qclient, qserver), benchmarks (qperf/qperf2), tests, and a draft-parser tool.

##### File structure to extract the architecture
- Top-level executables in cmd/: qserver (relay), qclient examples, qperf/qperf2 (benchmarks).
- Core library under include/quicr and src/:
- API layer (client.h, server.h, common.h, config.h)
- Control-message subsystem (ctrl_message_types, ctrl_messages)
- Track handlers (publish_fetch, publish_track, fetch_track, subscribe_track, joining_fetch)
- Storage & scheduling (data_storage, safe_queue, time_queue, priority_queue)
- Transport abstraction (quic_transport, transport_picoquic)
- Utilities (hash, uintvar, metrics).
- External dependencies: mbedTLS/BoringSSL, picoquic/picotls, spdlog, doctest, Python/Jinja (draft_parser).

##### README for additional insights
- Describes Client/Server examples (qclient, qserver) and usage.
- Mentions the relay pattern: server accepts connections and relays objects to subscribers.
- Highlights TLS (cert/key) for server, build & test targets.

##### Main components
- qserver executable (uses Server API)
- qclient executable (uses Client API; can publish, subscribe, or both)
- qperf/qperf2 (benchmark clients)
- draft_parser (tool to generate code from protocol drafts)
- API layer: Client API, Server API
- Control Message Processor: control message parsing and dispatch
- Track Handlers: publish, subscribe, fetch, joining
- Storage & Queues: data_storage, time_queue, safe_queue, priority_queue
- Transport Abstraction: quic_transport interface
- QUIC stack: picoquic + picotls
- TLS library: mbedTLS or BoringSSL
d. External/support services
- Metrics (spdlog)
- Testing (doctest)
- Codegen (Python + Jinja templates for tools/draft_parser)

##### Relationships and interactions
- Client API → Control Message Processor → Transport Abstraction → QUIC/TLS → Network → Server transport
- Server transport → Control Message Processor → Track Handlers → Data Storage/Queues
- Publish path: Client publishes → control/data messages over QUIC → server’s publish handler → data_storage → dispatch to subscriber handlers → back over QUIC to clients
- Subscribe path: Client subscribes → control message → server’s subscribe handler → storage lookup or queued messages → data stream to client
- Benchmarks drive the same paths at scale; draft_parser is a separate offline code-generation tool.

##### Architectural patterns and design principles
- Layered architecture: clear separation of API, message handling, storage, transport, and external libs.
- Publish-subscribe messaging pattern implemented via track handlers and data storage.
- Abstraction of transport so the same API works over different QUIC/TLS implementations.
- Asynchronous/event-driven design using tick_service/time_queue.
- Single Responsibility Principle: each module (handler, storage, transport) has a focused role.

##### Elements
- Blue rectangles for library modules
- Green rectangles for external libraries
- Grey rectangles for executables/tools

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Applications Layer
    subgraph "Applications" 
        direction TB
        qclient["qclient"]:::exe
        qserver["qserver"]:::exe
        qperf["qperf"]:::exe
        qperf2["qperf2"]:::exe
        draft_parser["draft_parser"]:::tool
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        ClientAPI["Client API"]:::lib
        ServerAPI["Server API"]:::lib
        CommonAPI["Common API"]:::lib
    end

    %% Control Message Processor
    subgraph "Control Message Processor"
        direction TB
        CtrlTypes["ctrl_message_types"]:::lib
        CtrlMessages["ctrl_messages"]:::lib
    end

    %% Track Handlers
    subgraph "Track Handlers"
        direction TB
        PublishFetch["publish_fetch_handler"]:::lib
        PublishTrack["publish_track_handler"]:::lib
        FetchTrack["fetch_track_handler"]:::lib
        SubscribeTrack["subscribe_track_handler"]:::lib
        JoiningFetch["joining_fetch_handler"]:::lib
    end

    %% Storage & Scheduling
    subgraph "Storage & Scheduling"
        direction TB
        DataStorage["data_storage"]:::lib
        SafeQueue["safe_queue"]:::lib
        TimeQueue["time_queue"]:::lib
        PriorityQueue["priority_queue"]:::lib
    end

    %% Transport Abstraction
    subgraph "Transport Abstraction"
        direction TB
        QuicTransport["quic_transport"]:::lib
        TransportGlue["transport (generic)"]:::lib
        PicoquicTrans["transport_picoquic"]:::lib
    end

    %% Underlying Protocols & Security
    subgraph "Underlying Protocols & Security"
        direction TB
        Picoquic["picoquic"]:::ext
        Picotls["picotls"]:::ext
        TLSLib["mbedTLS/BoringSSL"]:::ext
    end

    %% Utilities & External
    subgraph "Utilities & Tools"
        direction TB
        Metrics["metrics (spdlog)"]:::ext
        Tests["tests (doctest)"]:::ext
        Codegen["codegen (Python/Jinja)"]:::ext
    end

    %% Flows
    qclient -->|"uses"| ClientAPI
    qserver -->|"uses"| ServerAPI
    qperf -->|"benchmark"| ClientAPI
    qperf2 -->|"benchmark"| ClientAPI
    draft_parser -->|"generates code"| Codegen

    ClientAPI -->|"control/data"| CtrlTypes
    ClientAPI -->|"control/data"| CtrlMessages
    ServerAPI -->|"control/data"| CtrlTypes
    ServerAPI -->|"control/data"| CtrlMessages

    CtrlTypes -->|"dispatch"| PublishFetch
    CtrlTypes -->|"dispatch"| PublishTrack
    CtrlTypes -->|"dispatch"| FetchTrack
    CtrlTypes -->|"dispatch"| SubscribeTrack
    CtrlTypes -->|"dispatch"| JoiningFetch

    PublishFetch --> DataStorage
    PublishTrack --> DataStorage
    FetchTrack --> DataStorage
    SubscribeTrack --> DataStorage
    JoiningFetch --> DataStorage

    DataStorage --> SafeQueue
    DataStorage --> TimeQueue
    DataStorage --> PriorityQueue

    CtrlMessages --> QuicTransport
    QuicTransport --> TransportGlue
    TransportGlue --> PicoquicTrans

    PicoquicTrans --> Picoquic
    PicoquicTrans --> Picotls
    PicoquicTrans --> TLSLib

    ClientAPI --> Metrics
    ServerAPI --> Metrics
    Tests --> ClientAPI
    Tests --> ServerAPI
    Tests --> DataStorage
    Tests --> SafeQueue
    Tests --> TimeQueue
    Tests --> PriorityQueue
    Tests --> PublishFetch
    Tests --> PublishTrack
    Tests --> FetchTrack
    Tests --> SubscribeTrack
    Tests --> CtrlTypes
    Tests --> CtrlMessages

    %% Click Events
    click qserver "https://github.com/quicr/libquicr/blob/main/cmd/examples/server.cpp"
    click qclient "https://github.com/quicr/libquicr/blob/main/cmd/examples/client.cpp"
    click qperf "https://github.com/quicr/libquicr/blob/main/cmd/qperf/qperf.cpp"
    click qperf2 "https://github.com/quicr/libquicr/blob/main/cmd/qperf2/qperf_pub.cc"
    click draft_parser "https://github.com/quicr/libquicr/blob/main/tools/draft_parser/main.py"
    click ClientAPI "https://github.com/quicr/libquicr/blob/main/include/quicr/client.h"
    click ServerAPI "https://github.com/quicr/libquicr/blob/main/include/quicr/server.h"
    click CommonAPI "https://github.com/quicr/libquicr/blob/main/include/quicr/common.h"
    click CtrlTypes "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/ctrl_message_types.h"
    click CtrlMessages "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/ctrl_messages.h"
    click PublishFetch "https://github.com/quicr/libquicr/blob/main/include/quicr/publish_fetch_handler.h"
    click PublishTrack "https://github.com/quicr/libquicr/blob/main/include/quicr/publish_track_handler.h"
    click FetchTrack "https://github.com/quicr/libquicr/blob/main/include/quicr/fetch_track_handler.h"
    click SubscribeTrack "https://github.com/quicr/libquicr/blob/main/include/quicr/subscribe_track_handler.h"
    click JoiningFetch "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/joining_fetch_handler.h"
    click DataStorage "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/data_storage.h"
    click SafeQueue "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/safe_queue.h"
    click TimeQueue "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/time_queue.h"
    click PriorityQueue "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/priority_queue.h"
    click QuicTransport "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/quic_transport.h"
    click PicoquicTrans "https://github.com/quicr/libquicr/blob/main/src/transport_picoquic.cpp"
    click TransportGlue "https://github.com/quicr/libquicr/blob/main/include/quicr/detail/transport.h"

    %% Styles
    classDef exe fill:#cccccc,stroke:#333,stroke-width:1px
    classDef lib fill:#a3c4f3,stroke:#0366d6,stroke-width:1px
    classDef ext fill:#b3e6b3,stroke:#2d862d,stroke-width:1px
    classDef tool fill:#e0b3ff,stroke:#7d3c98,stroke-width:1px
```
