# nodejs/undici architecture

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

- Interactive diagram: https://gitdiagram.com/nodejs/undici
- Repository: https://github.com/nodejs/undici

## Overview

Undici is a Node.js HTTP client with both low-level dispatch APIs and Web-compatible Fetch APIs. A typical request enters through the exported API, is dispatched through a client/connection pool, and is encoded and parsed by an HTTP protocol implementation before a response reaches the caller. The repository also provides pooling and proxy options, middleware-like interceptors, caching, and Web APIs such as Fetch, WebSocket, and EventSource. Several capability links are documented rather than verified from sampled implementation files.

Main entry points: [`index.js`](https://github.com/nodejs/undici/blob/main/index.js) (Undici exports), [`lib/dispatcher/client.js`](https://github.com/nodejs/undici/blob/main/lib/dispatcher/client.js) (Dispatcher), [`lib/interceptor/cache.js`](https://github.com/nodejs/undici/blob/main/lib/interceptor/cache.js) (Cache interceptor), [`lib/dispatcher/client-h1.js`](https://github.com/nodejs/undici/blob/main/lib/dispatcher/client-h1.js) (HTTP/1 client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Public interfaces"]
  node_exports["Undici exports<br/>[index.js]"]
  node_api["Request APIs"]
end

subgraph group_transport["Dispatch and transport"]
  node_dispatcher["Dispatcher<br/>[client.js]"]
  node_request["Request state<br/>[request.js]"]
  node_pool["Connection pools<br/>[pool.js]"]
  node_clienth1["HTTP/1 client<br/>[client-h1.js]"]
  node_clienth2["HTTP/2 client<br/>[client-h2.js]"]
  node_parser["HTTP/1 parser<br/>[llhttp-wasm.js]"]
end

subgraph group_middleware["Interceptors and cache"]
  node_interceptors["Interceptors"]
  node_cache["Cache interceptor<br/>[cache.js]"]
  node_cachehandler["Cache handler<br/>[cache-handler.js]"]
  node_memorystore[("Memory cache")]
  node_sqlite[("SQLite cache")]
end

subgraph group_web["Web APIs"]
  node_fetch["Fetch API<br/>[index.js]"]
  node_websocket["WebSocket<br/>[websocket.js]"]
  node_eventsource["EventSource<br/>[eventsource.js]"]
  node_cookies["Cookies<br/>[index.js]"]
  node_webcache["Cache Storage<br/>[cachestorage.js]"]
end

node_user(("Application"))
node_origin(("HTTP service"))

node_user -->|"uses"| node_exports
node_exports -->|"exports"| node_api
node_exports -->|"exports"| node_dispatcher
node_user -->|"calls"| node_fetch
node_api -.->|"dispatches"| node_dispatcher
node_fetch -.->|"dispatches"| node_dispatcher
node_dispatcher -->|"creates"| node_request
node_dispatcher -->|"uses"| node_clienth1
node_dispatcher -->|"uses"| node_clienth2
node_pool -.->|"manages"| node_dispatcher
node_clienth1 -->|"parses with"| node_parser
node_clienth1 -.->|"sends HTTP"| node_origin
node_clienth2 -.->|"sends HTTP/2"| node_origin
node_exports -->|"exports"| node_interceptors
node_interceptors -->|"includes"| node_cache
node_cache -->|"uses"| node_cachehandler
node_cache -->|"defaults to"| node_memorystore
node_cache -.->|"supports"| node_sqlite
node_cachehandler -->|"reads and writes"| node_memorystore
node_exports -.->|"exports"| node_websocket
node_exports -.->|"exports"| node_eventsource
node_exports -->|"exports"| node_cookies
node_exports -->|"exports"| node_webcache

click node_exports "https://github.com/nodejs/undici/blob/main/index.js"
click node_api "https://github.com/nodejs/undici/tree/main/lib/api"
click node_fetch "https://github.com/nodejs/undici/blob/main/lib/web/fetch/index.js"
click node_dispatcher "https://github.com/nodejs/undici/blob/main/lib/dispatcher/client.js"
click node_request "https://github.com/nodejs/undici/blob/main/lib/core/request.js"
click node_pool "https://github.com/nodejs/undici/blob/main/lib/dispatcher/pool.js"
click node_clienth1 "https://github.com/nodejs/undici/blob/main/lib/dispatcher/client-h1.js"
click node_clienth2 "https://github.com/nodejs/undici/blob/main/lib/dispatcher/client-h2.js"
click node_parser "https://github.com/nodejs/undici/blob/main/lib/llhttp/llhttp-wasm.js"
click node_interceptors "https://github.com/nodejs/undici/tree/main/lib/interceptor"
click node_cache "https://github.com/nodejs/undici/blob/main/lib/interceptor/cache.js"
click node_cachehandler "https://github.com/nodejs/undici/blob/main/lib/handler/cache-handler.js"
click node_memorystore "https://github.com/nodejs/undici/blob/main/lib/cache/memory-cache-store.js"
click node_sqlite "https://github.com/nodejs/undici/blob/main/lib/cache/sqlite-cache-store.js"
click node_websocket "https://github.com/nodejs/undici/blob/main/lib/web/websocket/websocket.js"
click node_eventsource "https://github.com/nodejs/undici/blob/main/lib/web/eventsource/eventsource.js"
click node_cookies "https://github.com/nodejs/undici/blob/main/lib/web/cookies/index.js"
click node_webcache "https://github.com/nodejs/undici/blob/main/lib/web/cache/cachestorage.js"

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_exports,node_api toneBlue
class node_dispatcher,node_request,node_pool,node_clienth1,node_clienth2,node_parser toneAmber
class node_interceptors,node_cache,node_cachehandler,node_memorystore,node_sqlite toneMint
class node_fetch,node_websocket,node_eventsource,node_cookies,node_webcache toneRose
class node_user,node_origin toneIndigo
```

## Components

### Public interfaces

- [Undici exports](https://github.com/nodejs/undici/blob/main/index.js): `index.js`
- [Request APIs](https://github.com/nodejs/undici/tree/main/lib/api): `lib/api`

### Dispatch and transport

- [Dispatcher](https://github.com/nodejs/undici/blob/main/lib/dispatcher/client.js): `lib/dispatcher/client.js`
- [Request state](https://github.com/nodejs/undici/blob/main/lib/core/request.js): `lib/core/request.js`
- [Connection pools](https://github.com/nodejs/undici/blob/main/lib/dispatcher/pool.js): `lib/dispatcher/pool.js`
- [HTTP/1 client](https://github.com/nodejs/undici/blob/main/lib/dispatcher/client-h1.js): `lib/dispatcher/client-h1.js`
- [HTTP/2 client](https://github.com/nodejs/undici/blob/main/lib/dispatcher/client-h2.js): `lib/dispatcher/client-h2.js`
- [HTTP/1 parser](https://github.com/nodejs/undici/blob/main/lib/llhttp/llhttp-wasm.js): `lib/llhttp/llhttp-wasm.js`

### Interceptors and cache

- [Interceptors](https://github.com/nodejs/undici/tree/main/lib/interceptor): `lib/interceptor`
- [Cache interceptor](https://github.com/nodejs/undici/blob/main/lib/interceptor/cache.js): `lib/interceptor/cache.js`
- [Cache handler](https://github.com/nodejs/undici/blob/main/lib/handler/cache-handler.js): `lib/handler/cache-handler.js`
- [Memory cache](https://github.com/nodejs/undici/blob/main/lib/cache/memory-cache-store.js): `lib/cache/memory-cache-store.js`
- [SQLite cache](https://github.com/nodejs/undici/blob/main/lib/cache/sqlite-cache-store.js): `lib/cache/sqlite-cache-store.js`

### Web APIs

- [Fetch API](https://github.com/nodejs/undici/blob/main/lib/web/fetch/index.js): `lib/web/fetch/index.js`
- [WebSocket](https://github.com/nodejs/undici/blob/main/lib/web/websocket/websocket.js): `lib/web/websocket/websocket.js`
- [EventSource](https://github.com/nodejs/undici/blob/main/lib/web/eventsource/eventsource.js): `lib/web/eventsource/eventsource.js`
- [Cookies](https://github.com/nodejs/undici/blob/main/lib/web/cookies/index.js): `lib/web/cookies/index.js`
- [Cache Storage](https://github.com/nodejs/undici/blob/main/lib/web/cache/cachestorage.js): `lib/web/cache/cachestorage.js`

### Other components

- **Application**
- **HTTP service**

## Connections

- Application → Undici exports: uses (evidence: `README.md`)
- Undici exports → Request APIs: exports (evidence: `index.js`)
- Undici exports → Dispatcher: exports (evidence: `index.js`)
- Application → Fetch API: calls (evidence: `README.md`)
- Request APIs → Dispatcher: dispatches
- Fetch API → Dispatcher: dispatches
- Dispatcher → Request state: creates (evidence: `lib/dispatcher/client.js`)
- Dispatcher → HTTP/1 client: uses (evidence: `lib/dispatcher/client.js`)
- Dispatcher → HTTP/2 client: uses (evidence: `lib/dispatcher/client.js`)
- Connection pools → Dispatcher: manages
- HTTP/1 client → HTTP/1 parser: parses with (evidence: `lib/dispatcher/client-h1.js`)
- HTTP/1 client → HTTP service: sends HTTP
- HTTP/2 client → HTTP service: sends HTTP/2
- Undici exports → Interceptors: exports (evidence: `index.js`)
- Interceptors → Cache interceptor: includes (evidence: `index.js`)
- Cache interceptor → Cache handler: uses (evidence: `lib/interceptor/cache.js`)
- Cache interceptor → Memory cache: defaults to (evidence: `lib/interceptor/cache.js`)
- Cache interceptor → SQLite cache: supports
- Cache handler → Memory cache: reads and writes (evidence: `lib/handler/cache-handler.js`)
- Undici exports → WebSocket: exports
- Undici exports → EventSource: exports
- Undici exports → Cookies: exports (evidence: `index.js`)
- Undici exports → Cache Storage: exports (evidence: `index.js`)
