# cloudflare/workerd architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/workerd
- Repository: https://github.com/cloudflare/workerd

## Overview

workerd is Cloudflare’s JavaScript/Wasm server runtime, used to host Workers, develop them locally, and proxy HTTP traffic. The principal flow is configuration defining Workers and sockets, the server binding listeners to services, and a Worker handling an incoming request to produce a response. The graph also preserves documented capability bindings and major runtime API families. The README and sampled server header support the entry-point relationships; unsampled subsystem links are shown only as dashed, unverified relationships.

Main entry points: [`src/workerd/io/worker-entrypoint.h`](https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker-entrypoint.h) (Worker Entrypoint), [`src/workerd/server/server.h`](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/server.h) (Server), [`src/workerd/io/worker.h`](https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker.h) (Service Routing), [`src/workerd/server/workerd.capnp`](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp) (Runtime Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serve["Server and Services"]
  node_config["Runtime Config<br/>[workerd.capnp]"]
  node_server["Server<br/>[server.h]"]
  node_socket["HTTP Socket<br/>[sockets.h]"]
  node_service["Service Routing<br/>[worker.h]"]
end

subgraph group_execution["Worker Execution"]
  node_worker["Worker Entrypoint"]
  node_modules["Module Loading<br/>[worker-loader.h]"]
  node_isolate["Isolate Runtime<br/>[main.ts]"]
end

subgraph group_apis["Worker APIs"]
  node_streams["Web Streams<br/>[streams.ts]"]
  node_http["HTTP APIs<br/>[http.h]"]
  node_cloudflare["Cloudflare APIs<br/>[workers.ts]"]
end

subgraph group_state["State and Bindings"]
  node_bindings["Service Bindings<br/>[worker-rpc.h]"]
  node_actors["Durable Objects<br/>[actor.h]"]
  node_storage[("Actor Storage<br/>[actor-storage.h]")]
end

subgraph group_compat["Runtime Compatibility"]
  node_node["Node Compatibility<br/>[http.ts]"]
  node_python["Python Runtime"]
end

node_operator(("Operator"))
node_external["External Resources"]
node_response["HTTP Response"]

node_operator -->|"configures"| node_config
node_operator -->|"starts"| node_server
node_config -.->|"configures"| node_server
node_server -.->|"binds listeners"| node_socket
node_socket -.->|"routes requests"| node_service
node_service -.->|"dispatches"| node_worker
node_worker -->|"returns"| node_response
node_worker -.->|"loads modules"| node_modules
node_worker -.->|"executes in"| node_isolate
node_worker -->|"handles fetch"| node_http
node_worker -.->|"uses streams"| node_streams
node_worker -.->|"uses APIs"| node_cloudflare
node_worker -.->|"uses compatibility APIs"| node_node
node_worker -.->|"runs Python"| node_python
node_worker -->|"calls services"| node_bindings
node_bindings -->|"dispatches locally"| node_service
node_worker -.->|"uses actors"| node_actors
node_actors -.->|"persists state"| node_storage
node_worker -->|"accesses capabilities"| node_external
node_server -.->|"constructs workers"| node_worker

click node_config "https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp"
click node_server "https://github.com/cloudflare/workerd/blob/main/src/workerd/server/server.h"
click node_socket "https://github.com/cloudflare/workerd/blob/main/src/workerd/api/sockets.h"
click node_service "https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker.h"
click node_worker "https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker-entrypoint.h"
click node_modules "https://github.com/cloudflare/workerd/blob/main/src/workerd/api/worker-loader.h"
click node_isolate "https://github.com/cloudflare/workerd/blob/main/src/per_isolate/main.ts"
click node_streams "https://github.com/cloudflare/workerd/blob/main/src/per_isolate/webstreams/streams.ts"
click node_http "https://github.com/cloudflare/workerd/blob/main/src/workerd/api/http.h"
click node_cloudflare "https://github.com/cloudflare/workerd/blob/main/src/cloudflare/workers.ts"
click node_node "https://github.com/cloudflare/workerd/blob/main/src/node/http.ts"
click node_bindings "https://github.com/cloudflare/workerd/blob/main/src/workerd/api/worker-rpc.h"
click node_actors "https://github.com/cloudflare/workerd/blob/main/src/workerd/api/actor.h"
click node_storage "https://github.com/cloudflare/workerd/blob/main/src/workerd/io/actor-storage.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_config,node_server,node_socket,node_service toneBlue
class node_worker,node_modules,node_isolate toneAmber
class node_streams,node_http,node_cloudflare toneMint
class node_bindings,node_actors,node_storage toneRose
class node_node,node_python,node_operator,node_external,node_response toneIndigo
```

## Components

### Server and Services

- [Runtime Config](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/workerd.capnp): `src/workerd/server/workerd.capnp`
- [Server](https://github.com/cloudflare/workerd/blob/main/src/workerd/server/server.h): `src/workerd/server/server.h`
- [HTTP Socket](https://github.com/cloudflare/workerd/blob/main/src/workerd/api/sockets.h): `src/workerd/api/sockets.h`
- [Service Routing](https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker.h): `src/workerd/io/worker.h`

### Worker Execution

- [Worker Entrypoint](https://github.com/cloudflare/workerd/blob/main/src/workerd/io/worker-entrypoint.h): `src/workerd/io/worker-entrypoint.h`
- [Module Loading](https://github.com/cloudflare/workerd/blob/main/src/workerd/api/worker-loader.h): `src/workerd/api/worker-loader.h`
- [Isolate Runtime](https://github.com/cloudflare/workerd/blob/main/src/per_isolate/main.ts): `src/per_isolate/main.ts`

### Worker APIs

- [Web Streams](https://github.com/cloudflare/workerd/blob/main/src/per_isolate/webstreams/streams.ts): `src/per_isolate/webstreams/streams.ts`
- [HTTP APIs](https://github.com/cloudflare/workerd/blob/main/src/workerd/api/http.h): `src/workerd/api/http.h`
- [Cloudflare APIs](https://github.com/cloudflare/workerd/blob/main/src/cloudflare/workers.ts): `src/cloudflare/workers.ts`

### State and Bindings

- [Service Bindings](https://github.com/cloudflare/workerd/blob/main/src/workerd/api/worker-rpc.h): `src/workerd/api/worker-rpc.h`
- [Durable Objects](https://github.com/cloudflare/workerd/blob/main/src/workerd/api/actor.h): `src/workerd/api/actor.h`
- [Actor Storage](https://github.com/cloudflare/workerd/blob/main/src/workerd/io/actor-storage.h): `src/workerd/io/actor-storage.h`

### Runtime Compatibility

- [Node Compatibility](https://github.com/cloudflare/workerd/blob/main/src/node/http.ts): `src/node/http.ts`
- **Python Runtime**

### Other components

- **Operator**
- **External Resources**
- **HTTP Response**

## Connections

- Operator → Runtime Config: configures
- Operator → Server: starts
- Runtime Config → Server: configures
- Server → HTTP Socket: binds listeners
- HTTP Socket → Service Routing: routes requests
- Service Routing → Worker Entrypoint: dispatches
- Worker Entrypoint → HTTP Response: returns
- Worker Entrypoint → Module Loading: loads modules
- Worker Entrypoint → Isolate Runtime: executes in
- Worker Entrypoint → HTTP APIs: handles fetch
- Worker Entrypoint → Web Streams: uses streams
- Worker Entrypoint → Cloudflare APIs: uses APIs
- Worker Entrypoint → Node Compatibility: uses compatibility APIs
- Worker Entrypoint → Python Runtime: runs Python
- Worker Entrypoint → Service Bindings: calls services
- Service Bindings → Service Routing: dispatches locally
- Worker Entrypoint → Durable Objects: uses actors
- Durable Objects → Actor Storage: persists state
- Worker Entrypoint → External Resources: accesses capabilities
- Server → Worker Entrypoint: constructs workers
