# dart-lang/shelf architecture

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

- Interactive diagram: https://gitdiagram.com/dart-lang/shelf
- Repository: https://github.com/dart-lang/shelf

## Overview

Shelf is a Dart toolkit for creating and composing web servers around request-to-response handlers, with middleware as its central composition model. Its packages add routing, static and package-directory serving, proxying, WebSockets, test interactions, and HTTP compliance coverage; the router generator produces routers from source annotations. No source excerpts were provided, so relationships below are limited to capabilities and dependencies explicitly described in the README.

Main entry points: [`pkgs/shelf/lib/src/handler.dart`](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/handler.dart) (Shelf handlers), [`pkgs/shelf/lib/src/pipeline.dart`](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/pipeline.dart) (Middleware composition), [`pkgs/shelf_router/lib/src/router.dart`](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router/lib/src/router.dart) (Request router), [`pkgs/shelf_router_generator/lib/src/shelf_router_generator.dart`](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router_generator/lib/src/shelf_router_generator.dart) (Router generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Shelf core"]
  node_shelf["Shelf handlers<br/>[handler.dart]"]
  node_middleware["Middleware composition<br/>[pipeline.dart]"]
  node_http_model["Request and response<br/>[message.dart]"]
end

subgraph group_routing["Routing"]
  node_router["Request router<br/>[router.dart]"]
  node_router_routes["Route matching<br/>[route.dart]"]
  node_router_generator["Router generator"]
end

subgraph group_handlers["Server handlers"]
  node_package_dir["Packages directory<br/>[dir_handler.dart]"]
  node_proxy["HTTP proxy<br/>[shelf_proxy.dart]"]
  node_static_files["Static files"]
  node_directory_listing["Directory listing"]
  node_websocket["WebSocket handler"]
end

subgraph group_quality["Testing and compliance"]
  node_test_handler["HTTP test handler<br/>[handler.dart]"]
  node_compliance["HTTP compliance"]
end

node_developer(("Application developer"))

node_developer -->|"creates servers"| node_shelf
node_developer -->|"composes middleware"| node_middleware
node_shelf -->|"handles requests"| node_http_model
node_middleware -->|"composes handlers"| node_shelf
node_router -->|"routes requests"| node_shelf
node_router_generator -->|"generates routers"| node_router
node_package_dir -->|"provides handler"| node_shelf
node_proxy -->|"provides handler"| node_shelf
node_static_files -->|"serves files"| node_shelf
node_websocket -->|"provides handler"| node_shelf
node_test_handler -->|"tests interactions"| node_shelf
node_compliance -->|"checks compliance"| node_shelf

click node_shelf "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/handler.dart"
click node_middleware "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/pipeline.dart"
click node_http_model "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/message.dart"
click node_router "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router/lib/src/router.dart"
click node_router_routes "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router/lib/src/route.dart"
click node_router_generator "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router_generator/lib/src/shelf_router_generator.dart"
click node_package_dir "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_packages_handler/lib/src/dir_handler.dart"
click node_proxy "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_proxy/lib/shelf_proxy.dart"
click node_static_files "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_static/lib/src/static_handler.dart"
click node_directory_listing "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_static/lib/src/directory_listing.dart"
click node_websocket "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_web_socket/lib/src/web_socket_handler.dart"
click node_test_handler "https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_test_handler/lib/src/handler.dart"
click node_compliance "https://github.com/dart-lang/shelf/blob/master/pkgs/_shelf_compliance/lib/src/compliance_harness.dart"

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_shelf,node_middleware,node_http_model toneBlue
class node_router,node_router_routes,node_router_generator toneAmber
class node_package_dir,node_proxy,node_static_files,node_directory_listing,node_websocket toneMint
class node_test_handler,node_compliance toneRose
class node_developer toneIndigo
```

## Components

### Shelf core

- [Shelf handlers](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/handler.dart): `pkgs/shelf/lib/src/handler.dart`
- [Middleware composition](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/pipeline.dart): `pkgs/shelf/lib/src/pipeline.dart`
- [Request and response](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf/lib/src/message.dart): `pkgs/shelf/lib/src/message.dart`

### Routing

- [Request router](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router/lib/src/router.dart): `pkgs/shelf_router/lib/src/router.dart`
- [Route matching](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router/lib/src/route.dart): `pkgs/shelf_router/lib/src/route.dart`
- [Router generator](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_router_generator/lib/src/shelf_router_generator.dart): `pkgs/shelf_router_generator/lib/src/shelf_router_generator.dart`

### Server handlers

- [Packages directory](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_packages_handler/lib/src/dir_handler.dart): `pkgs/shelf_packages_handler/lib/src/dir_handler.dart`
- [HTTP proxy](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_proxy/lib/shelf_proxy.dart): `pkgs/shelf_proxy/lib/shelf_proxy.dart`
- [Static files](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_static/lib/src/static_handler.dart): `pkgs/shelf_static/lib/src/static_handler.dart`
- [Directory listing](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_static/lib/src/directory_listing.dart): `pkgs/shelf_static/lib/src/directory_listing.dart`
- [WebSocket handler](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_web_socket/lib/src/web_socket_handler.dart): `pkgs/shelf_web_socket/lib/src/web_socket_handler.dart`

### Testing and compliance

- [HTTP test handler](https://github.com/dart-lang/shelf/blob/master/pkgs/shelf_test_handler/lib/src/handler.dart): `pkgs/shelf_test_handler/lib/src/handler.dart`
- [HTTP compliance](https://github.com/dart-lang/shelf/blob/master/pkgs/_shelf_compliance/lib/src/compliance_harness.dart): `pkgs/_shelf_compliance/lib/src/compliance_harness.dart`

### Other components

- **Application developer**

## Connections

- Application developer → Shelf handlers: creates servers (evidence: `README.md`)
- Application developer → Middleware composition: composes middleware (evidence: `README.md`)
- Shelf handlers → Request and response: handles requests (evidence: `README.md`)
- Middleware composition → Shelf handlers: composes handlers (evidence: `README.md`)
- Request router → Shelf handlers: routes requests (evidence: `README.md`)
- Router generator → Request router: generates routers (evidence: `README.md`)
- Packages directory → Shelf handlers: provides handler (evidence: `README.md`)
- HTTP proxy → Shelf handlers: provides handler (evidence: `README.md`)
- Static files → Shelf handlers: serves files (evidence: `README.md`)
- WebSocket handler → Shelf handlers: provides handler (evidence: `README.md`)
- HTTP test handler → Shelf handlers: tests interactions (evidence: `README.md`)
- HTTP compliance → Shelf handlers: checks compliance (evidence: `README.md`)