# emmett-framework/granian architecture

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

- Interactive diagram: https://gitdiagram.com/emmett-framework/granian
- Repository: https://github.com/emmett-framework/granian

## Overview

Granian is a Rust-backed HTTP server for Python applications. The principal workflow is configuring a server, starting worker processes, accepting HTTP connections, dispatching requests through the selected ASGI, RSGI, or WSGI adapter, and returning responses to clients. Its documented capabilities also include WebSockets, TLS/mTLS, static files, and metrics. The excerpts and source index support the main Rust worker, protocol, networking, runtime, and metrics relationships; some Python startup wiring and unsampled feature internals are not shown, so those links are omitted.

Main entry points: [`src/workers.rs`](https://github.com/emmett-framework/granian/blob/master/src/workers.rs) (Connection Workers), [`src/asgi/serve.rs`](https://github.com/emmett-framework/granian/blob/master/src/asgi/serve.rs) (ASGI Serving), [`granian/server/common.py`](https://github.com/emmett-framework/granian/blob/master/granian/server/common.py) (Worker Supervisor), [`src/rsgi/serve.rs`](https://github.com/emmett-framework/granian/blob/master/src/rsgi/serve.rs) (RSGI Serving)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Control Plane"]
  node_cli["CLI Configuration<br/>[cli.py]"]
  node_supervisor["Worker Supervisor<br/>[common.py]"]
  node_process_workers["Process Workers<br/>[mp.py]"]
  node_thread_workers["Thread Workers<br/>[mt.py]"]
end

subgraph group_core["Rust Server Core"]
  node_worker_accept["Connection Workers<br/>[workers.rs]"]
  node_serve_runtime["Serve Runtime<br/>[serve.rs]"]
  node_listener["Socket Listeners<br/>[net.rs]"]
end

subgraph group_protocols["Python Interfaces"]
  node_asgi["ASGI Adapter<br/>[io.rs]"]
  node_asgi_dispatch["ASGI Serving<br/>[serve.rs]"]
  node_rsgi["RSGI Adapter<br/>[io.rs]"]
  node_rsgi_dispatch["RSGI Serving<br/>[serve.rs]"]
  node_wsgi["WSGI Adapter<br/>[io.rs]"]
  node_wsgi_dispatch["WSGI Serving<br/>[serve.rs]"]
end

subgraph group_features["HTTP Features"]
  node_http["HTTP Protocol<br/>[http.rs]"]
  node_websockets["WebSockets<br/>[ws.rs]"]
  node_tls["TLS and mTLS<br/>[tls.rs]"]
  node_static_files["Static Files<br/>[files.rs]"]
end

subgraph group_ops["Runtime and Metrics"]
  node_runtime["Async Runtime<br/>[runtime.rs]"]
  node_callbacks["Python Callbacks<br/>[callbacks.rs]"]
  node_metrics["Metrics Export<br/>[metrics.rs]"]
  node_ipc["Worker IPC<br/>[ipc.rs]"]
end

node_operator(("Server Operator"))
node_app(("Python Application"))
node_client(("HTTP Client"))

node_operator -->|"configures"| node_cli
node_app -->|"target to serve"| node_supervisor
node_cli -.->|"starts server"| node_supervisor
node_supervisor -.->|"spawns"| node_process_workers
node_supervisor -.->|"selects mode"| node_thread_workers
node_process_workers -.->|"runs workers"| node_worker_accept
node_thread_workers -.->|"runs workers"| node_worker_accept
node_worker_accept -->|"accepts connections"| node_listener
node_worker_accept -->|"dispatches requests"| node_asgi_dispatch
node_worker_accept -->|"dispatches requests"| node_rsgi_dispatch
node_worker_accept -->|"dispatches requests"| node_wsgi_dispatch
node_asgi_dispatch -->|"serves via"| node_serve_runtime
node_rsgi_dispatch -->|"serves via"| node_serve_runtime
node_wsgi_dispatch -->|"serves via"| node_serve_runtime
node_asgi_dispatch -->|"handles HTTP"| node_http
node_rsgi_dispatch -->|"handles HTTP"| node_http
node_wsgi_dispatch -->|"handles HTTP"| node_http
node_asgi -.->|"adapts requests"| node_asgi_dispatch
node_rsgi -.->|"adapts requests"| node_rsgi_dispatch
node_wsgi -.->|"adapts requests"| node_wsgi_dispatch
node_worker_accept -->|"checks mounts"| node_static_files
node_worker_accept -->|"configures TLS"| node_tls
node_worker_accept -->|"updates metrics"| node_metrics
node_serve_runtime -->|"runs tasks"| node_runtime
node_runtime -->|"uses callbacks"| node_callbacks
node_worker_accept -->|"uses worker IPC"| node_ipc
node_metrics -->|"collects worker data"| node_ipc
node_client -->|"opens connection"| node_listener
node_http -.->|"returns response"| node_client
node_asgi_dispatch -.->|"supports WebSockets"| node_websockets

click node_cli "https://github.com/emmett-framework/granian/blob/master/granian/cli.py"
click node_supervisor "https://github.com/emmett-framework/granian/blob/master/granian/server/common.py"
click node_process_workers "https://github.com/emmett-framework/granian/blob/master/granian/server/mp.py"
click node_thread_workers "https://github.com/emmett-framework/granian/blob/master/granian/server/mt.py"
click node_worker_accept "https://github.com/emmett-framework/granian/blob/master/src/workers.rs"
click node_serve_runtime "https://github.com/emmett-framework/granian/blob/master/src/serve.rs"
click node_listener "https://github.com/emmett-framework/granian/blob/master/src/net.rs"
click node_asgi "https://github.com/emmett-framework/granian/blob/master/src/asgi/io.rs"
click node_asgi_dispatch "https://github.com/emmett-framework/granian/blob/master/src/asgi/serve.rs"
click node_rsgi "https://github.com/emmett-framework/granian/blob/master/src/rsgi/io.rs"
click node_rsgi_dispatch "https://github.com/emmett-framework/granian/blob/master/src/rsgi/serve.rs"
click node_wsgi "https://github.com/emmett-framework/granian/blob/master/src/wsgi/io.rs"
click node_wsgi_dispatch "https://github.com/emmett-framework/granian/blob/master/src/wsgi/serve.rs"
click node_http "https://github.com/emmett-framework/granian/blob/master/src/http.rs"
click node_websockets "https://github.com/emmett-framework/granian/blob/master/src/ws.rs"
click node_tls "https://github.com/emmett-framework/granian/blob/master/src/tls.rs"
click node_static_files "https://github.com/emmett-framework/granian/blob/master/src/files.rs"
click node_runtime "https://github.com/emmett-framework/granian/blob/master/src/runtime.rs"
click node_callbacks "https://github.com/emmett-framework/granian/blob/master/src/callbacks.rs"
click node_metrics "https://github.com/emmett-framework/granian/blob/master/src/metrics.rs"
click node_ipc "https://github.com/emmett-framework/granian/blob/master/src/ipc.rs"

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_cli,node_supervisor,node_process_workers,node_thread_workers,node_client toneBlue
class node_worker_accept,node_serve_runtime,node_listener toneAmber
class node_asgi,node_asgi_dispatch,node_rsgi,node_rsgi_dispatch,node_wsgi,node_wsgi_dispatch,node_operator toneMint
class node_http,node_websockets,node_tls,node_static_files toneRose
class node_runtime,node_callbacks,node_metrics,node_ipc,node_app toneIndigo
```

## Components

### Python Control Plane

- [CLI Configuration](https://github.com/emmett-framework/granian/blob/master/granian/cli.py): `granian/cli.py`
- [Worker Supervisor](https://github.com/emmett-framework/granian/blob/master/granian/server/common.py): `granian/server/common.py`
- [Process Workers](https://github.com/emmett-framework/granian/blob/master/granian/server/mp.py): `granian/server/mp.py`
- [Thread Workers](https://github.com/emmett-framework/granian/blob/master/granian/server/mt.py): `granian/server/mt.py`

### Rust Server Core

- [Connection Workers](https://github.com/emmett-framework/granian/blob/master/src/workers.rs): `src/workers.rs`
- [Serve Runtime](https://github.com/emmett-framework/granian/blob/master/src/serve.rs): `src/serve.rs`
- [Socket Listeners](https://github.com/emmett-framework/granian/blob/master/src/net.rs): `src/net.rs`

### Python Interfaces

- [ASGI Adapter](https://github.com/emmett-framework/granian/blob/master/src/asgi/io.rs): `src/asgi/io.rs`
- [ASGI Serving](https://github.com/emmett-framework/granian/blob/master/src/asgi/serve.rs): `src/asgi/serve.rs`
- [RSGI Adapter](https://github.com/emmett-framework/granian/blob/master/src/rsgi/io.rs): `src/rsgi/io.rs`
- [RSGI Serving](https://github.com/emmett-framework/granian/blob/master/src/rsgi/serve.rs): `src/rsgi/serve.rs`
- [WSGI Adapter](https://github.com/emmett-framework/granian/blob/master/src/wsgi/io.rs): `src/wsgi/io.rs`
- [WSGI Serving](https://github.com/emmett-framework/granian/blob/master/src/wsgi/serve.rs): `src/wsgi/serve.rs`

### HTTP Features

- [HTTP Protocol](https://github.com/emmett-framework/granian/blob/master/src/http.rs): `src/http.rs`
- [WebSockets](https://github.com/emmett-framework/granian/blob/master/src/ws.rs): `src/ws.rs`
- [TLS and mTLS](https://github.com/emmett-framework/granian/blob/master/src/tls.rs): `src/tls.rs`
- [Static Files](https://github.com/emmett-framework/granian/blob/master/src/files.rs): `src/files.rs`

### Runtime and Metrics

- [Async Runtime](https://github.com/emmett-framework/granian/blob/master/src/runtime.rs): `src/runtime.rs`
- [Python Callbacks](https://github.com/emmett-framework/granian/blob/master/src/callbacks.rs): `src/callbacks.rs`
- [Metrics Export](https://github.com/emmett-framework/granian/blob/master/src/metrics.rs): `src/metrics.rs`
- [Worker IPC](https://github.com/emmett-framework/granian/blob/master/src/ipc.rs): `src/ipc.rs`

### Other components

- **Server Operator**
- **Python Application**
- **HTTP Client**

## Connections

- Server Operator → CLI Configuration: configures (evidence: `README.md`)
- Python Application → Worker Supervisor: target to serve (evidence: `README.md`)
- CLI Configuration → Worker Supervisor: starts server
- Worker Supervisor → Process Workers: spawns (evidence: `granian/server/mp.py`)
- Worker Supervisor → Thread Workers: selects mode (evidence: `granian/server/mt.py`)
- Process Workers → Connection Workers: runs workers
- Thread Workers → Connection Workers: runs workers
- Connection Workers → Socket Listeners: accepts connections (evidence: `src/workers.rs`)
- Connection Workers → ASGI Serving: dispatches requests (evidence: `src/workers.rs`)
- Connection Workers → RSGI Serving: dispatches requests (evidence: `src/workers.rs`)
- Connection Workers → WSGI Serving: dispatches requests (evidence: `src/workers.rs`)
- ASGI Serving → Serve Runtime: serves via (evidence: `src/asgi/serve.rs`)
- RSGI Serving → Serve Runtime: serves via (evidence: `src/rsgi/serve.rs`)
- WSGI Serving → Serve Runtime: serves via (evidence: `src/wsgi/serve.rs`)
- ASGI Serving → HTTP Protocol: handles HTTP (evidence: `src/asgi/serve.rs`)
- RSGI Serving → HTTP Protocol: handles HTTP (evidence: `src/rsgi/serve.rs`)
- WSGI Serving → HTTP Protocol: handles HTTP (evidence: `src/wsgi/serve.rs`)
- ASGI Adapter → ASGI Serving: adapts requests
- RSGI Adapter → RSGI Serving: adapts requests
- WSGI Adapter → WSGI Serving: adapts requests
- Connection Workers → Static Files: checks mounts (evidence: `src/workers.rs`)
- Connection Workers → TLS and mTLS: configures TLS (evidence: `src/workers.rs`)
- Connection Workers → Metrics Export: updates metrics (evidence: `src/workers.rs`)
- Serve Runtime → Async Runtime: runs tasks (evidence: `src/serve.rs`)
- Async Runtime → Python Callbacks: uses callbacks (evidence: `src/runtime.rs`)
- Connection Workers → Worker IPC: uses worker IPC (evidence: `src/workers.rs`)
- Metrics Export → Worker IPC: collects worker data (evidence: `src/metrics.rs`)
- HTTP Client → Socket Listeners: opens connection (evidence: `README.md`)
- HTTP Protocol → HTTP Client: returns response
- ASGI Serving → WebSockets: supports WebSockets (evidence: `README.md`)
