# tokio-rs/axum architecture

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

- Interactive diagram: https://gitdiagram.com/tokio-rs/axum
- Repository: https://github.com/tokio-rs/axum

## Overview

Axum is a Rust HTTP routing and request-handling library. Its main workflow accepts an HTTP request at a listener, dispatches it through a router and method-specific handler, extracts typed inputs, and converts the handler result into an HTTP response. Supporting branches provide Tower-compatible middleware and services, derive macros, and axum-extra extractors, routing, bodies, and response types. The README documents these capabilities; some links below are documented or index-backed because their implementation excerpts were not provided.

Main entry points: [`axum-core/src/extract/mod.rs`](https://github.com/tokio-rs/axum/blob/main/axum-core/src/extract/mod.rs) (Extractor traits), [`axum/src/handler/mod.rs`](https://github.com/tokio-rs/axum/blob/main/axum/src/handler/mod.rs) (Handler service), [`axum/src/routing/mod.rs`](https://github.com/tokio-rs/axum/blob/main/axum/src/routing/mod.rs) (Path router), [`axum-core/src/response/mod.rs`](https://github.com/tokio-rs/axum/blob/main/axum-core/src/response/mod.rs) (Response conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP runtime"]
  node_serve["HTTP serving<br/>[mod.rs]"]
  node_router["Path router<br/>[mod.rs]"]
  node_path_dispatch["Route dispatch<br/>[path_router.rs]"]
  node_method_route["Method routing<br/>[method_routing.rs]"]
  node_handler["Handler service<br/>[mod.rs]"]
end

subgraph group_request["Request processing"]
  node_extract_traits["Extractor traits<br/>[mod.rs]"]
  node_extractors["Request extractors<br/>[mod.rs]"]
  node_query["Query parsing<br/>[query.rs]"]
  node_connect["Connection info<br/>[connect_info.rs]"]
  node_body["HTTP body<br/>[body.rs]"]
end

subgraph group_response["Responses"]
  node_responses["Response conversion<br/>[mod.rs]"]
  node_response_types["Response types<br/>[mod.rs]"]
  node_sse["Server events<br/>[sse.rs]"]
end

subgraph group_extensions["Ecosystem extensions"]
  node_middleware["Tower middleware<br/>[mod.rs]"]
  node_extra_extract["Extra extractors"]
  node_extra_response["Extra responses"]
  node_extra_routing["Extra routing<br/>[mod.rs]"]
  node_extra_body["Extra body tools"]
end

subgraph group_macros["Derive macros"]
  node_macros["Procedural macros<br/>[lib.rs]"]
  node_attr_parsing["Attribute parsing<br/>[attr_parsing.rs]"]
  node_debug_handler["Handler diagnostics<br/>[debug_handler.rs]"]
end

node_client(("HTTP client"))
node_tower["Tower ecosystem"]

node_client -->|"sends requests"| node_serve
node_serve -->|"serves service"| node_router
node_router -->|"dispatches paths"| node_path_dispatch
node_path_dispatch -->|"selects route"| node_method_route
node_method_route -->|"calls handler"| node_handler
node_handler -->|"extracts arguments"| node_extract_traits
node_extractors -->|"implements traits"| node_extract_traits
node_query -->|"implements extraction"| node_extract_traits
node_connect -->|"implements extraction"| node_extract_traits
node_extract_traits -->|"consumes request body"| node_body
node_handler -->|"converts result"| node_responses
node_response_types -->|"uses conversion traits"| node_responses
node_response_types -->|"exports events"| node_sse
node_handler -.->|"uses service layers"| node_middleware
node_tower -.->|"provides services"| node_middleware
node_extra_extract -.->|"extends extraction"| node_extract_traits
node_extra_response -.->|"extends responses"| node_responses
node_extra_routing -.->|"extends routing"| node_router
node_macros -->|"parses attributes"| node_attr_parsing
node_macros -->|"provides diagnostics"| node_debug_handler

click node_serve "https://github.com/tokio-rs/axum/blob/main/axum/src/serve/mod.rs"
click node_router "https://github.com/tokio-rs/axum/blob/main/axum/src/routing/mod.rs"
click node_path_dispatch "https://github.com/tokio-rs/axum/blob/main/axum/src/routing/path_router.rs"
click node_method_route "https://github.com/tokio-rs/axum/blob/main/axum/src/routing/method_routing.rs"
click node_handler "https://github.com/tokio-rs/axum/blob/main/axum/src/handler/mod.rs"
click node_extract_traits "https://github.com/tokio-rs/axum/blob/main/axum-core/src/extract/mod.rs"
click node_extractors "https://github.com/tokio-rs/axum/blob/main/axum/src/extract/mod.rs"
click node_query "https://github.com/tokio-rs/axum/blob/main/axum/src/extract/query.rs"
click node_connect "https://github.com/tokio-rs/axum/blob/main/axum/src/extract/connect_info.rs"
click node_body "https://github.com/tokio-rs/axum/blob/main/axum-core/src/body.rs"
click node_responses "https://github.com/tokio-rs/axum/blob/main/axum-core/src/response/mod.rs"
click node_response_types "https://github.com/tokio-rs/axum/blob/main/axum/src/response/mod.rs"
click node_sse "https://github.com/tokio-rs/axum/blob/main/axum/src/response/sse.rs"
click node_middleware "https://github.com/tokio-rs/axum/blob/main/axum/src/middleware/mod.rs"
click node_extra_extract "https://github.com/tokio-rs/axum/tree/main/axum-extra/src/extract"
click node_extra_response "https://github.com/tokio-rs/axum/tree/main/axum-extra/src/response"
click node_extra_routing "https://github.com/tokio-rs/axum/blob/main/axum-extra/src/routing/mod.rs"
click node_extra_body "https://github.com/tokio-rs/axum/tree/main/axum-extra/src/body"
click node_macros "https://github.com/tokio-rs/axum/blob/main/axum-macros/src/lib.rs"
click node_attr_parsing "https://github.com/tokio-rs/axum/blob/main/axum-macros/src/attr_parsing.rs"
click node_debug_handler "https://github.com/tokio-rs/axum/blob/main/axum-macros/src/debug_handler.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_serve,node_router,node_path_dispatch,node_method_route,node_handler,node_client toneBlue
class node_extract_traits,node_extractors,node_query,node_connect,node_body toneAmber
class node_responses,node_response_types,node_sse toneMint
class node_middleware,node_extra_extract,node_extra_response,node_extra_routing,node_extra_body toneRose
class node_macros,node_attr_parsing,node_debug_handler,node_tower toneIndigo
```

## Components

### HTTP runtime

- [HTTP serving](https://github.com/tokio-rs/axum/blob/main/axum/src/serve/mod.rs): `axum/src/serve/mod.rs`
- [Path router](https://github.com/tokio-rs/axum/blob/main/axum/src/routing/mod.rs): `axum/src/routing/mod.rs`
- [Route dispatch](https://github.com/tokio-rs/axum/blob/main/axum/src/routing/path_router.rs): `axum/src/routing/path_router.rs`
- [Method routing](https://github.com/tokio-rs/axum/blob/main/axum/src/routing/method_routing.rs): `axum/src/routing/method_routing.rs`
- [Handler service](https://github.com/tokio-rs/axum/blob/main/axum/src/handler/mod.rs): `axum/src/handler/mod.rs`

### Request processing

- [Extractor traits](https://github.com/tokio-rs/axum/blob/main/axum-core/src/extract/mod.rs): `axum-core/src/extract/mod.rs`
- [Request extractors](https://github.com/tokio-rs/axum/blob/main/axum/src/extract/mod.rs): `axum/src/extract/mod.rs`
- [Query parsing](https://github.com/tokio-rs/axum/blob/main/axum/src/extract/query.rs): `axum/src/extract/query.rs`
- [Connection info](https://github.com/tokio-rs/axum/blob/main/axum/src/extract/connect_info.rs): `axum/src/extract/connect_info.rs`
- [HTTP body](https://github.com/tokio-rs/axum/blob/main/axum-core/src/body.rs): `axum-core/src/body.rs`

### Responses

- [Response conversion](https://github.com/tokio-rs/axum/blob/main/axum-core/src/response/mod.rs): `axum-core/src/response/mod.rs`
- [Response types](https://github.com/tokio-rs/axum/blob/main/axum/src/response/mod.rs): `axum/src/response/mod.rs`
- [Server events](https://github.com/tokio-rs/axum/blob/main/axum/src/response/sse.rs): `axum/src/response/sse.rs`

### Ecosystem extensions

- [Tower middleware](https://github.com/tokio-rs/axum/blob/main/axum/src/middleware/mod.rs): `axum/src/middleware/mod.rs`
- [Extra extractors](https://github.com/tokio-rs/axum/tree/main/axum-extra/src/extract): `axum-extra/src/extract`
- [Extra responses](https://github.com/tokio-rs/axum/tree/main/axum-extra/src/response): `axum-extra/src/response`
- [Extra routing](https://github.com/tokio-rs/axum/blob/main/axum-extra/src/routing/mod.rs): `axum-extra/src/routing/mod.rs`
- [Extra body tools](https://github.com/tokio-rs/axum/tree/main/axum-extra/src/body): `axum-extra/src/body`

### Derive macros

- [Procedural macros](https://github.com/tokio-rs/axum/blob/main/axum-macros/src/lib.rs): `axum-macros/src/lib.rs`
- [Attribute parsing](https://github.com/tokio-rs/axum/blob/main/axum-macros/src/attr_parsing.rs): `axum-macros/src/attr_parsing.rs`
- [Handler diagnostics](https://github.com/tokio-rs/axum/blob/main/axum-macros/src/debug_handler.rs): `axum-macros/src/debug_handler.rs`

### Other components

- **HTTP client**
- **Tower ecosystem**

## Connections

- HTTP client → HTTP serving: sends requests (evidence: `README.md`)
- HTTP serving → Path router: serves service (evidence: `axum/src/serve/mod.rs`)
- Path router → Route dispatch: dispatches paths (evidence: `axum/src/routing/mod.rs`)
- Route dispatch → Method routing: selects route (evidence: `axum/src/routing/path_router.rs`)
- Method routing → Handler service: calls handler (evidence: `axum/src/routing/method_routing.rs`)
- Handler service → Extractor traits: extracts arguments (evidence: `axum/src/handler/mod.rs`)
- Request extractors → Extractor traits: implements traits (evidence: `axum/src/extract/mod.rs`)
- Query parsing → Extractor traits: implements extraction (evidence: `axum/src/extract/query.rs`)
- Connection info → Extractor traits: implements extraction (evidence: `axum/src/extract/connect_info.rs`)
- Extractor traits → HTTP body: consumes request body (evidence: `axum-core/src/extract/mod.rs`)
- Handler service → Response conversion: converts result (evidence: `axum-core/src/response/mod.rs`)
- Response types → Response conversion: uses conversion traits (evidence: `axum/src/response/mod.rs`)
- Response types → Server events: exports events (evidence: `axum/src/response/mod.rs`)
- Handler service → Tower middleware: uses service layers (evidence: `README.md`)
- Tower ecosystem → Tower middleware: provides services (evidence: `README.md`)
- Extra extractors → Extractor traits: extends extraction
- Extra responses → Response conversion: extends responses
- Extra routing → Path router: extends routing
- Procedural macros → Attribute parsing: parses attributes (evidence: `axum-macros/src/lib.rs`)
- Procedural macros → Handler diagnostics: provides diagnostics (evidence: `axum-macros/src/lib.rs`)
