# aio-libs/aiohttp architecture

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

- Interactive diagram: https://gitdiagram.com/aio-libs/aiohttp
- Repository: https://github.com/aio-libs/aiohttp

## Overview

aiohttp is an asyncio HTTP client/server framework, with WebSocket support on both sides. Its client workflow builds a request, obtains a connection, exchanges HTTP data, and exposes a response; its server workflow accepts a request, dispatches a route through middleware to a handler, and sends a response. WebSocket handling branches from HTTP upgrade on each side. The tree and README establish these capabilities; sampled excerpts chiefly confirm client request/response, connector, and frame-processing responsibilities, so uncertain internal links are omitted.

Main entry points: [`aiohttp/client.py`](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client.py) (Client session), [`aiohttp/client_reqrep.py`](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_reqrep.py) (Client request/response), [`aiohttp/web_app.py`](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_app.py) (Application and routes), [`aiohttp/web_protocol.py`](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_protocol.py) (Server protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["HTTP client"]
  node_client_session["Client session<br/>[client.py]"]
  node_client_req["Client request/response<br/>[client_reqrep.py]"]
  node_connector["Connection pool<br/>[connector.py]"]
  node_client_proto["Client protocol<br/>[client_proto.py]"]
  node_digest["Digest middleware"]
end

subgraph group_server["HTTP server"]
  node_web_app["Application and routes<br/>[web_app.py]"]
  node_middleware["Server middleware<br/>[web_middlewares.py]"]
  node_dispatcher["URL dispatcher"]
  node_web_request["Server request<br/>[web_request.py]"]
  node_web_response["Server response<br/>[web_response.py]"]
  node_web_protocol["Server protocol<br/>[web_protocol.py]"]
  node_web_server["Server lifecycle<br/>[web_server.py]"]
end

subgraph group_wire["HTTP and streams"]
  node_http_parser["HTTP parser<br/>[http_parser.py]"]
  node_http_writer["HTTP writer<br/>[http_writer.py]"]
  node_streams["Async streams<br/>[streams.py]"]
end

subgraph group_websocket["WebSocket"]
  node_client_ws["Client WebSocket<br/>[client_ws.py]"]
  node_server_ws["Server WebSocket<br/>[web_ws.py]"]
  node_ws_reader["Frame reader<br/>[reader.py]"]
  node_ws_writer["Frame writer<br/>[writer.py]"]
end

subgraph group_support["Request support"]
  node_payload["Payload encoding<br/>[payload.py]"]
  node_multipart["Multipart forms<br/>[multipart.py]"]
  node_cookiejar["Cookie jar<br/>[cookiejar.py]"]
end

node_caller(("Application code"))
node_remote(("Remote HTTP peer"))
node_listener(("Incoming HTTP peer"))
node_handler(("Route handler"))

node_caller -->|"requests through"| node_client_session
node_client_session -->|"creates and sends"| node_client_req
node_client_session -->|"acquires connection"| node_connector
node_client_req -->|"sends request"| node_connector
node_connector -->|"exchanges transport data"| node_remote
node_client_proto -->|"parses response data"| node_http_parser
node_http_parser -->|"feeds body bytes"| node_streams
node_client_req -->|"encodes request body"| node_payload
node_client_session -->|"manages cookies"| node_cookiejar
node_digest -.->|"middleware integration"| node_client_session
node_listener -->|"connects to"| node_web_server
node_web_server -->|"serves protocol"| node_web_protocol
node_web_protocol -->|"parses request data"| node_http_parser
node_http_parser -->|"provides parsed request"| node_web_request
node_web_protocol -->|"dispatches request"| node_web_app
node_web_app -->|"applies middleware"| node_middleware
node_web_app -->|"resolves route"| node_dispatcher
node_dispatcher -->|"invokes handler"| node_handler
node_handler -->|"returns response"| node_web_response
node_web_protocol -->|"writes response"| node_http_writer
node_web_response -->|"serializes response"| node_http_writer
node_http_writer -->|"sends HTTP data"| node_remote
node_web_app -->|"supports upgrade handler"| node_server_ws
node_client_session -->|"initiates upgrade"| node_client_ws
node_client_ws -->|"reads frames"| node_ws_reader
node_client_ws -->|"writes frames"| node_ws_writer
node_server_ws -->|"reads frames"| node_ws_reader
node_server_ws -->|"writes frames"| node_ws_writer
node_ws_reader -->|"queues messages"| node_streams
node_ws_writer -->|"sends frames"| node_remote
node_client_req -->|"parses disposition"| node_multipart

click node_client_session "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client.py"
click node_client_req "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_reqrep.py"
click node_connector "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/connector.py"
click node_client_proto "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_proto.py"
click node_digest "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_middleware_digest_auth.py"
click node_web_app "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_app.py"
click node_middleware "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_middlewares.py"
click node_dispatcher "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_urldispatcher.py"
click node_web_request "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_request.py"
click node_web_response "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_response.py"
click node_web_protocol "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_protocol.py"
click node_web_server "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_server.py"
click node_http_parser "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/http_parser.py"
click node_http_writer "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/http_writer.py"
click node_streams "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/streams.py"
click node_payload "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/payload.py"
click node_multipart "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/multipart.py"
click node_cookiejar "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/cookiejar.py"
click node_client_ws "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_ws.py"
click node_server_ws "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_ws.py"
click node_ws_reader "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/_websocket/reader.py"
click node_ws_writer "https://github.com/aio-libs/aiohttp/blob/master/aiohttp/_websocket/writer.py"

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_client_session,node_client_req,node_connector,node_client_proto,node_digest toneBlue
class node_web_app,node_middleware,node_dispatcher,node_web_request,node_web_response,node_web_protocol,node_web_server toneAmber
class node_http_parser,node_http_writer,node_streams,node_handler toneMint
class node_client_ws,node_server_ws,node_ws_reader,node_ws_writer toneRose
class node_payload,node_multipart,node_cookiejar,node_caller,node_remote,node_listener toneIndigo
```

## Components

### HTTP client

- [Client session](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client.py): `aiohttp/client.py`
- [Client request/response](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_reqrep.py): `aiohttp/client_reqrep.py`
- [Connection pool](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/connector.py): `aiohttp/connector.py`
- [Client protocol](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_proto.py): `aiohttp/client_proto.py`
- [Digest middleware](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_middleware_digest_auth.py): `aiohttp/client_middleware_digest_auth.py`

### HTTP server

- [Application and routes](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_app.py): `aiohttp/web_app.py`
- [Server middleware](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_middlewares.py): `aiohttp/web_middlewares.py`
- [URL dispatcher](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_urldispatcher.py): `aiohttp/web_urldispatcher.py`
- [Server request](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_request.py): `aiohttp/web_request.py`
- [Server response](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_response.py): `aiohttp/web_response.py`
- [Server protocol](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_protocol.py): `aiohttp/web_protocol.py`
- [Server lifecycle](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_server.py): `aiohttp/web_server.py`

### HTTP and streams

- [HTTP parser](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/http_parser.py): `aiohttp/http_parser.py`
- [HTTP writer](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/http_writer.py): `aiohttp/http_writer.py`
- [Async streams](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/streams.py): `aiohttp/streams.py`

### WebSocket

- [Client WebSocket](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client_ws.py): `aiohttp/client_ws.py`
- [Server WebSocket](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/web_ws.py): `aiohttp/web_ws.py`
- [Frame reader](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/_websocket/reader.py): `aiohttp/_websocket/reader.py`
- [Frame writer](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/_websocket/writer.py): `aiohttp/_websocket/writer.py`

### Request support

- [Payload encoding](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/payload.py): `aiohttp/payload.py`
- [Multipart forms](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/multipart.py): `aiohttp/multipart.py`
- [Cookie jar](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/cookiejar.py): `aiohttp/cookiejar.py`

### Other components

- **Application code**
- **Remote HTTP peer**
- **Incoming HTTP peer**
- **Route handler**

## Connections

- Application code → Client session: requests through
- Client session → Client request/response: creates and sends
- Client session → Connection pool: acquires connection
- Client request/response → Connection pool: sends request
- Connection pool → Remote HTTP peer: exchanges transport data
- Client protocol → HTTP parser: parses response data
- HTTP parser → Async streams: feeds body bytes
- Client request/response → Payload encoding: encodes request body
- Client session → Cookie jar: manages cookies
- Digest middleware → Client session: middleware integration
- Incoming HTTP peer → Server lifecycle: connects to
- Server lifecycle → Server protocol: serves protocol
- Server protocol → HTTP parser: parses request data
- HTTP parser → Server request: provides parsed request
- Server protocol → Application and routes: dispatches request
- Application and routes → Server middleware: applies middleware
- Application and routes → URL dispatcher: resolves route
- URL dispatcher → Route handler: invokes handler
- Route handler → Server response: returns response
- Server protocol → HTTP writer: writes response
- Server response → HTTP writer: serializes response
- HTTP writer → Remote HTTP peer: sends HTTP data
- Application and routes → Server WebSocket: supports upgrade handler
- Client session → Client WebSocket: initiates upgrade
- Client WebSocket → Frame reader: reads frames
- Client WebSocket → Frame writer: writes frames
- Server WebSocket → Frame reader: reads frames
- Server WebSocket → Frame writer: writes frames
- Frame reader → Async streams: queues messages
- Frame writer → Remote HTTP peer: sends frames
- Client request/response → Multipart forms: parses disposition