# facebook/mvfst architecture

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

- Interactive diagram: https://gitdiagram.com/facebook/mvfst
- Repository: https://github.com/facebook/mvfst

## Overview

mvfst is a C++ implementation of the QUIC transport protocol, with client and server transports for applications. The principal workflow is an application opening a connection and exchanging reliable multiplexed streams over UDP; handshake, packet processing, stream/connection state, flow control, loss recovery, and congestion control support that exchange. The README also documents server scaling and routing, restart support, statistics, zero-RTT, GSO, and client address racing. Relationships below follow the documented architecture and sampled source; unsampled subsystem wiring is kept conservative.

Main entry points: [`quic/client/QuicClientTransportLite.cpp`](https://github.com/facebook/mvfst/blob/main/quic/client/QuicClientTransportLite.cpp) (Client Transport), [`quic/server/QuicServerWorker.cpp`](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerWorker.cpp) (Server Worker), [`quic/api`](https://github.com/facebook/mvfst/tree/main/quic/api) (Transport API), [`quic/server/QuicServer.cpp`](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServer.cpp) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_api["Transport API"]
end

subgraph group_endpoints["Client and Server"]
  node_client["Client Transport"]
  node_happy["Address Racing"]
  node_server["Server<br/>[QuicServer.cpp]"]
  node_worker["Server Worker"]
  node_router["Packet Router"]
end

subgraph group_protocol["QUIC Protocol"]
  node_handshake["Handshake<br/>[HandshakeLayer.cpp]"]
  node_fizz["Fizz TLS"]
  node_codec["Packet Codec"]
  node_state["Connection State<br/>[StateData.h]"]
  node_streams["Stream Manager"]
  node_flow["Flow Control"]
  node_datagrams["Datagram Flows"]
end

subgraph group_runtime["Transport Runtime"]
  node_udp["UDP Socket"]
  node_scheduler["Packet Scheduling"]
  node_congestion["Congestion Control"]
  node_loss["Loss Recovery"]
  node_events["Event Timers<br/>[QuicEventBase.h]"]
end

subgraph group_operations["Deployment Features"]
  node_routing["CID Routing"]
  node_gso["UDP GSO"]
  node_stats["Transport Statistics<br/>[TransportInfo.h]"]
  node_qlog["QLog<br/>[QLogger.h]"]
end

node_app(("Application"))
node_network(("UDP Network"))

node_app -->|"uses"| node_api
node_api -->|"opens transport"| node_client
node_api -->|"configures server"| node_server
node_client -.->|"races addresses"| node_happy
node_client -->|"establishes session"| node_handshake
node_handshake -->|"uses TLS"| node_fizz
node_client -->|"encodes packets"| node_codec
node_client -->|"sends and receives"| node_udp
node_udp -->|"exchanges datagrams"| node_network
node_network -->|"delivers datagrams"| node_udp
node_server -->|"dispatches work"| node_worker
node_worker -->|"routes packets"| node_router
node_worker -->|"receives packets"| node_udp
node_worker -->|"decodes packets"| node_codec
node_worker -->|"establishes session"| node_handshake
node_codec -->|"updates connection"| node_state
node_state -->|"tracks streams"| node_streams
node_streams -->|"checks data limits"| node_flow
node_api -->|"queues datagrams"| node_datagrams
node_state -->|"provides send state"| node_scheduler
node_scheduler -->|"checks send allowance"| node_congestion
node_state -->|"tracks packet loss"| node_loss
node_client -->|"schedules transport work"| node_events
node_worker -->|"schedules transport work"| node_events
node_worker -->|"routes connection IDs"| node_routing
node_worker -.->|"configures packet writes"| node_gso
node_client -->|"reports statistics"| node_stats
node_server -->|"exposes statistics"| node_stats
node_client -.->|"records events"| node_qlog
node_server -.->|"records events"| node_qlog

click node_api "https://github.com/facebook/mvfst/tree/main/quic/api"
click node_client "https://github.com/facebook/mvfst/blob/main/quic/client/QuicClientTransportLite.cpp"
click node_happy "https://github.com/facebook/mvfst/tree/main/quic/happyeyeballs"
click node_server "https://github.com/facebook/mvfst/blob/main/quic/server/QuicServer.cpp"
click node_worker "https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerWorker.cpp"
click node_router "https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerPacketRouter.cpp"
click node_handshake "https://github.com/facebook/mvfst/blob/main/quic/handshake/HandshakeLayer.cpp"
click node_fizz "https://github.com/facebook/mvfst/tree/main/quic/fizz"
click node_codec "https://github.com/facebook/mvfst/tree/main/quic/codec"
click node_state "https://github.com/facebook/mvfst/blob/main/quic/state/StateData.h"
click node_streams "https://github.com/facebook/mvfst/blob/main/quic/state/QuicStreamManager.cpp"
click node_flow "https://github.com/facebook/mvfst/blob/main/quic/flowcontrol/QuicFlowController.cpp"
click node_datagrams "https://github.com/facebook/mvfst/blob/main/quic/datagram/DatagramFlowManager.cpp"
click node_udp "https://github.com/facebook/mvfst/blob/main/quic/common/udpsocket/QuicAsyncUDPSocket.h"
click node_scheduler "https://github.com/facebook/mvfst/blob/main/quic/api/QuicPacketScheduler.cpp"
click node_congestion "https://github.com/facebook/mvfst/blob/main/quic/congestion_control/CongestionControllerFactory.cpp"
click node_loss "https://github.com/facebook/mvfst/blob/main/quic/loss/QuicLossFunctions.cpp"
click node_events "https://github.com/facebook/mvfst/blob/main/quic/common/events/QuicEventBase.h"
click node_routing "https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerWorker.cpp"
click node_gso "https://github.com/facebook/mvfst/blob/main/quic/api/QuicBatchWriterFactory.h"
click node_stats "https://github.com/facebook/mvfst/blob/main/quic/api/TransportInfo.h"
click node_qlog "https://github.com/facebook/mvfst/blob/main/quic/logging/QLogger.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api toneBlue
class node_client,node_happy,node_server,node_worker,node_router toneAmber
class node_handshake,node_fizz,node_codec,node_state,node_streams,node_flow,node_datagrams toneMint
class node_udp,node_scheduler,node_congestion,node_loss,node_events toneRose
class node_routing,node_gso,node_stats,node_qlog,node_app,node_network toneIndigo
```

## Components

### Application API

- [Transport API](https://github.com/facebook/mvfst/tree/main/quic/api): `quic/api`

### Client and Server

- [Client Transport](https://github.com/facebook/mvfst/blob/main/quic/client/QuicClientTransportLite.cpp): `quic/client/QuicClientTransportLite.cpp`
- [Address Racing](https://github.com/facebook/mvfst/tree/main/quic/happyeyeballs): `quic/happyeyeballs`
- [Server](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServer.cpp): `quic/server/QuicServer.cpp`
- [Server Worker](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerWorker.cpp): `quic/server/QuicServerWorker.cpp`
- [Packet Router](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerPacketRouter.cpp): `quic/server/QuicServerPacketRouter.cpp`

### QUIC Protocol

- [Handshake](https://github.com/facebook/mvfst/blob/main/quic/handshake/HandshakeLayer.cpp): `quic/handshake/HandshakeLayer.cpp`
- [Fizz TLS](https://github.com/facebook/mvfst/tree/main/quic/fizz): `quic/fizz`
- [Packet Codec](https://github.com/facebook/mvfst/tree/main/quic/codec): `quic/codec`
- [Connection State](https://github.com/facebook/mvfst/blob/main/quic/state/StateData.h): `quic/state/StateData.h`
- [Stream Manager](https://github.com/facebook/mvfst/blob/main/quic/state/QuicStreamManager.cpp): `quic/state/QuicStreamManager.cpp`
- [Flow Control](https://github.com/facebook/mvfst/blob/main/quic/flowcontrol/QuicFlowController.cpp): `quic/flowcontrol/QuicFlowController.cpp`
- [Datagram Flows](https://github.com/facebook/mvfst/blob/main/quic/datagram/DatagramFlowManager.cpp): `quic/datagram/DatagramFlowManager.cpp`

### Transport Runtime

- [UDP Socket](https://github.com/facebook/mvfst/blob/main/quic/common/udpsocket/QuicAsyncUDPSocket.h): `quic/common/udpsocket/QuicAsyncUDPSocket.h`
- [Packet Scheduling](https://github.com/facebook/mvfst/blob/main/quic/api/QuicPacketScheduler.cpp): `quic/api/QuicPacketScheduler.cpp`
- [Congestion Control](https://github.com/facebook/mvfst/blob/main/quic/congestion_control/CongestionControllerFactory.cpp): `quic/congestion_control/CongestionControllerFactory.cpp`
- [Loss Recovery](https://github.com/facebook/mvfst/blob/main/quic/loss/QuicLossFunctions.cpp): `quic/loss/QuicLossFunctions.cpp`
- [Event Timers](https://github.com/facebook/mvfst/blob/main/quic/common/events/QuicEventBase.h): `quic/common/events/QuicEventBase.h`

### Deployment Features

- [CID Routing](https://github.com/facebook/mvfst/blob/main/quic/server/QuicServerWorker.cpp): `quic/server/QuicServerWorker.cpp`
- [UDP GSO](https://github.com/facebook/mvfst/blob/main/quic/api/QuicBatchWriterFactory.h): `quic/api/QuicBatchWriterFactory.h`
- [Transport Statistics](https://github.com/facebook/mvfst/blob/main/quic/api/TransportInfo.h): `quic/api/TransportInfo.h`
- [QLog](https://github.com/facebook/mvfst/blob/main/quic/logging/QLogger.h): `quic/logging/QLogger.h`

### Other components

- **Application**
- **UDP Network**

## Connections

- Application → Transport API: uses
- Transport API → Client Transport: opens transport
- Transport API → Server: configures server
- Client Transport → Address Racing: races addresses
- Client Transport → Handshake: establishes session
- Handshake → Fizz TLS: uses TLS
- Client Transport → Packet Codec: encodes packets
- Client Transport → UDP Socket: sends and receives
- UDP Socket → UDP Network: exchanges datagrams
- UDP Network → UDP Socket: delivers datagrams
- Server → Server Worker: dispatches work
- Server Worker → Packet Router: routes packets
- Server Worker → UDP Socket: receives packets
- Server Worker → Packet Codec: decodes packets
- Server Worker → Handshake: establishes session
- Packet Codec → Connection State: updates connection
- Connection State → Stream Manager: tracks streams
- Stream Manager → Flow Control: checks data limits
- Transport API → Datagram Flows: queues datagrams
- Connection State → Packet Scheduling: provides send state
- Packet Scheduling → Congestion Control: checks send allowance
- Connection State → Loss Recovery: tracks packet loss
- Client Transport → Event Timers: schedules transport work
- Server Worker → Event Timers: schedules transport work
- Server Worker → CID Routing: routes connection IDs
- Server Worker → UDP GSO: configures packet writes
- Client Transport → Transport Statistics: reports statistics
- Server → Transport Statistics: exposes statistics
- Client Transport → QLog: records events
- Server → QLog: records events