# tornadoweb/tornado architecture

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

- Interactive diagram: https://gitdiagram.com/tornadoweb/tornado
- Repository: https://github.com/tornadoweb/tornado

## Overview

Tornado is both a Python web framework and an asynchronous networking library. Its principal workflow accepts a network request, parses HTTP data, dispatches through application routing to a handler, and returns a response; its client API also issues asynchronous HTTP requests. The graph preserves documented WebSockets, authentication, templates, and locale support alongside the event-loop, transport, and client layers. Relationships use README statements or SOURCE INDEX references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`tornado/httpclient.py`](https://github.com/tornadoweb/tornado/blob/master/tornado/httpclient.py) (HTTP client API), [`tornado/httpserver.py`](https://github.com/tornadoweb/tornado/blob/master/tornado/httpserver.py) (HTTP server), [`tornado/simple_httpclient.py`](https://github.com/tornadoweb/tornado/blob/master/tornado/simple_httpclient.py) (Simple HTTP client), [`tornado/ioloop.py`](https://github.com/tornadoweb/tornado/blob/master/tornado/ioloop.py) (Event loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web framework"]
  node_application["Web application<br/>[web.py]"]
  node_routing["Request routing<br/>[routing.py]"]
  node_handlers["Request handlers<br/>[web.py]"]
  node_websocket["WebSockets<br/>[websocket.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_templates["Templates<br/>[template.py]"]
  node_locale["Localization<br/>[locale.py]"]
end

subgraph group_transport["HTTP transport"]
  node_httpserver["HTTP server<br/>[httpserver.py]"]
  node_http1["HTTP/1 connection<br/>[http1connection.py]"]
  node_httputil["HTTP messages<br/>[httputil.py]"]
  node_iostream["Stream I/O<br/>[iostream.py]"]
  node_tcpserver["TCP server<br/>[tcpserver.py]"]
  node_netutil["Network utilities<br/>[netutil.py]"]
end

subgraph group_async["Async runtime"]
  node_ioloop["Event loop<br/>[ioloop.py]"]
  node_gen["Coroutine support<br/>[gen.py]"]
  node_concurrent["Future utilities<br/>[concurrent.py]"]
  node_asyncio["Asyncio bridge<br/>[asyncio.py]"]
  node_locks["Async locks<br/>[locks.py]"]
  node_queues["Async queues<br/>[queues.py]"]
  node_process["Process management<br/>[process.py]"]
end

subgraph group_clients["HTTP clients"]
  node_httpclient["HTTP client API<br/>[httpclient.py]"]
  node_simpleclient["Simple HTTP client"]
  node_curlclient["Curl HTTP client<br/>[curl_httpclient.py]"]
end

subgraph group_support["Framework support"]
  node_escape["Encoding utilities<br/>[escape.py]"]
  node_options["Configuration options<br/>[options.py]"]
  node_logging["Logging<br/>[log.py]"]
end

node_user(("Application user"))

node_user -->|"configures routes"| node_application
node_user -->|"sends requests"| node_httpserver
node_application -->|"registers handlers"| node_handlers
node_application -->|"listens via"| node_httpserver
node_application -->|"uses routing"| node_routing
node_handlers -->|"uses templates"| node_templates
node_handlers -->|"uses localization"| node_locale
node_handlers -.->|"supports authentication"| node_auth
node_httpserver -->|"creates connections"| node_http1
node_httpserver -->|"uses TCP server"| node_tcpserver
node_httpserver -->|"uses HTTP messages"| node_httputil
node_httpserver -->|"uses streams"| node_iostream
node_httpserver -->|"uses networking"| node_netutil
node_http1 -->|"uses HTTP messages"| node_httputil
node_http1 -->|"uses streams"| node_iostream
node_tcpserver -->|"uses networking"| node_netutil
node_iostream -->|"registers I/O"| node_ioloop
node_websocket -->|"uses streams"| node_iostream
node_websocket -->|"uses HTTP client"| node_httpclient
node_websocket -->|"uses queues"| node_queues
node_ioloop -->|"integrates with"| node_asyncio
node_gen -->|"schedules coroutines"| node_ioloop
node_gen -->|"uses futures"| node_concurrent
node_locks -->|"uses coroutines"| node_gen
node_queues -->|"uses locks"| node_locks
node_process -->|"uses event loop"| node_ioloop
node_process -->|"uses futures"| node_concurrent
node_httpclient -->|"selects implementation"| node_simpleclient
node_httpclient -->|"uses HTTP messages"| node_httputil
node_httpclient -->|"uses event loop"| node_ioloop
node_simpleclient -->|"uses HTTP connection"| node_http1
node_simpleclient -->|"uses HTTP messages"| node_httputil
node_simpleclient -->|"uses streams"| node_iostream
node_simpleclient -->|"uses networking"| node_netutil
node_simpleclient -->|"implements interface"| node_httpclient
node_curlclient -->|"implements interface"| node_httpclient
node_curlclient -->|"uses event loop"| node_ioloop
node_auth -->|"makes HTTP requests"| node_httpclient
node_auth -->|"uses web framework"| node_handlers
node_templates -->|"uses escaping"| node_escape
node_locale -->|"uses escaping"| node_escape
node_locale -->|"uses logging"| node_logging
node_httpclient -->|"uses options"| node_options

click node_application "https://github.com/tornadoweb/tornado/blob/master/tornado/web.py"
click node_routing "https://github.com/tornadoweb/tornado/blob/master/tornado/routing.py"
click node_handlers "https://github.com/tornadoweb/tornado/blob/master/tornado/web.py"
click node_websocket "https://github.com/tornadoweb/tornado/blob/master/tornado/websocket.py"
click node_auth "https://github.com/tornadoweb/tornado/blob/master/tornado/auth.py"
click node_templates "https://github.com/tornadoweb/tornado/blob/master/tornado/template.py"
click node_locale "https://github.com/tornadoweb/tornado/blob/master/tornado/locale.py"
click node_httpserver "https://github.com/tornadoweb/tornado/blob/master/tornado/httpserver.py"
click node_http1 "https://github.com/tornadoweb/tornado/blob/master/tornado/http1connection.py"
click node_httputil "https://github.com/tornadoweb/tornado/blob/master/tornado/httputil.py"
click node_iostream "https://github.com/tornadoweb/tornado/blob/master/tornado/iostream.py"
click node_tcpserver "https://github.com/tornadoweb/tornado/blob/master/tornado/tcpserver.py"
click node_netutil "https://github.com/tornadoweb/tornado/blob/master/tornado/netutil.py"
click node_ioloop "https://github.com/tornadoweb/tornado/blob/master/tornado/ioloop.py"
click node_gen "https://github.com/tornadoweb/tornado/blob/master/tornado/gen.py"
click node_concurrent "https://github.com/tornadoweb/tornado/blob/master/tornado/concurrent.py"
click node_asyncio "https://github.com/tornadoweb/tornado/blob/master/tornado/platform/asyncio.py"
click node_locks "https://github.com/tornadoweb/tornado/blob/master/tornado/locks.py"
click node_queues "https://github.com/tornadoweb/tornado/blob/master/tornado/queues.py"
click node_process "https://github.com/tornadoweb/tornado/blob/master/tornado/process.py"
click node_httpclient "https://github.com/tornadoweb/tornado/blob/master/tornado/httpclient.py"
click node_simpleclient "https://github.com/tornadoweb/tornado/blob/master/tornado/simple_httpclient.py"
click node_curlclient "https://github.com/tornadoweb/tornado/blob/master/tornado/curl_httpclient.py"
click node_escape "https://github.com/tornadoweb/tornado/blob/master/tornado/escape.py"
click node_options "https://github.com/tornadoweb/tornado/blob/master/tornado/options.py"
click node_logging "https://github.com/tornadoweb/tornado/blob/master/tornado/log.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_application,node_routing,node_handlers,node_websocket,node_auth,node_templates,node_locale,node_user toneBlue
class node_httpserver,node_http1,node_httputil,node_iostream,node_tcpserver,node_netutil toneAmber
class node_ioloop,node_gen,node_concurrent,node_asyncio,node_locks,node_queues,node_process toneMint
class node_httpclient,node_simpleclient,node_curlclient toneRose
class node_escape,node_options,node_logging toneIndigo
```

## Components

### Web framework

- [Web application](https://github.com/tornadoweb/tornado/blob/master/tornado/web.py): `tornado/web.py`
- [Request routing](https://github.com/tornadoweb/tornado/blob/master/tornado/routing.py): `tornado/routing.py`
- [Request handlers](https://github.com/tornadoweb/tornado/blob/master/tornado/web.py): `tornado/web.py`
- [WebSockets](https://github.com/tornadoweb/tornado/blob/master/tornado/websocket.py): `tornado/websocket.py`
- [Authentication](https://github.com/tornadoweb/tornado/blob/master/tornado/auth.py): `tornado/auth.py`
- [Templates](https://github.com/tornadoweb/tornado/blob/master/tornado/template.py): `tornado/template.py`
- [Localization](https://github.com/tornadoweb/tornado/blob/master/tornado/locale.py): `tornado/locale.py`

### HTTP transport

- [HTTP server](https://github.com/tornadoweb/tornado/blob/master/tornado/httpserver.py): `tornado/httpserver.py`
- [HTTP/1 connection](https://github.com/tornadoweb/tornado/blob/master/tornado/http1connection.py): `tornado/http1connection.py`
- [HTTP messages](https://github.com/tornadoweb/tornado/blob/master/tornado/httputil.py): `tornado/httputil.py`
- [Stream I/O](https://github.com/tornadoweb/tornado/blob/master/tornado/iostream.py): `tornado/iostream.py`
- [TCP server](https://github.com/tornadoweb/tornado/blob/master/tornado/tcpserver.py): `tornado/tcpserver.py`
- [Network utilities](https://github.com/tornadoweb/tornado/blob/master/tornado/netutil.py): `tornado/netutil.py`

### Async runtime

- [Event loop](https://github.com/tornadoweb/tornado/blob/master/tornado/ioloop.py): `tornado/ioloop.py`
- [Coroutine support](https://github.com/tornadoweb/tornado/blob/master/tornado/gen.py): `tornado/gen.py`
- [Future utilities](https://github.com/tornadoweb/tornado/blob/master/tornado/concurrent.py): `tornado/concurrent.py`
- [Asyncio bridge](https://github.com/tornadoweb/tornado/blob/master/tornado/platform/asyncio.py): `tornado/platform/asyncio.py`
- [Async locks](https://github.com/tornadoweb/tornado/blob/master/tornado/locks.py): `tornado/locks.py`
- [Async queues](https://github.com/tornadoweb/tornado/blob/master/tornado/queues.py): `tornado/queues.py`
- [Process management](https://github.com/tornadoweb/tornado/blob/master/tornado/process.py): `tornado/process.py`

### HTTP clients

- [HTTP client API](https://github.com/tornadoweb/tornado/blob/master/tornado/httpclient.py): `tornado/httpclient.py`
- [Simple HTTP client](https://github.com/tornadoweb/tornado/blob/master/tornado/simple_httpclient.py): `tornado/simple_httpclient.py`
- [Curl HTTP client](https://github.com/tornadoweb/tornado/blob/master/tornado/curl_httpclient.py): `tornado/curl_httpclient.py`

### Framework support

- [Encoding utilities](https://github.com/tornadoweb/tornado/blob/master/tornado/escape.py): `tornado/escape.py`
- [Configuration options](https://github.com/tornadoweb/tornado/blob/master/tornado/options.py): `tornado/options.py`
- [Logging](https://github.com/tornadoweb/tornado/blob/master/tornado/log.py): `tornado/log.py`

### Other components

- **Application user**

## Connections

- Application user → Web application: configures routes
- Application user → HTTP server: sends requests
- Web application → Request handlers: registers handlers (evidence: `tornado/web.py`)
- Web application → HTTP server: listens via (evidence: `tornado/web.py`)
- Web application → Request routing: uses routing (evidence: `tornado/web.py`)
- Request handlers → Templates: uses templates (evidence: `tornado/web.py`)
- Request handlers → Localization: uses localization (evidence: `tornado/web.py`)
- Request handlers → Authentication: supports authentication (evidence: `tornado/auth.py`)
- HTTP server → HTTP/1 connection: creates connections (evidence: `tornado/httpserver.py`)
- HTTP server → TCP server: uses TCP server (evidence: `tornado/httpserver.py`)
- HTTP server → HTTP messages: uses HTTP messages (evidence: `tornado/httpserver.py`)
- HTTP server → Stream I/O: uses streams (evidence: `tornado/httpserver.py`)
- HTTP server → Network utilities: uses networking (evidence: `tornado/httpserver.py`)
- HTTP/1 connection → HTTP messages: uses HTTP messages (evidence: `tornado/http1connection.py`)
- HTTP/1 connection → Stream I/O: uses streams (evidence: `tornado/http1connection.py`)
- TCP server → Network utilities: uses networking (evidence: `tornado/tcpserver.py`)
- Stream I/O → Event loop: registers I/O (evidence: `tornado/iostream.py`)
- WebSockets → Stream I/O: uses streams (evidence: `tornado/websocket.py`)
- WebSockets → HTTP client API: uses HTTP client (evidence: `tornado/websocket.py`)
- WebSockets → Async queues: uses queues (evidence: `tornado/websocket.py`)
- Event loop → Asyncio bridge: integrates with (evidence: `tornado/ioloop.py`)
- Coroutine support → Event loop: schedules coroutines (evidence: `tornado/gen.py`)
- Coroutine support → Future utilities: uses futures (evidence: `tornado/gen.py`)
- Async locks → Coroutine support: uses coroutines (evidence: `tornado/locks.py`)
- Async queues → Async locks: uses locks (evidence: `tornado/queues.py`)
- Process management → Event loop: uses event loop (evidence: `tornado/process.py`)
- Process management → Future utilities: uses futures (evidence: `tornado/process.py`)
- HTTP client API → Simple HTTP client: selects implementation (evidence: `tornado/httpclient.py`)
- HTTP client API → HTTP messages: uses HTTP messages (evidence: `tornado/httpclient.py`)
- HTTP client API → Event loop: uses event loop (evidence: `tornado/httpclient.py`)
- Simple HTTP client → HTTP/1 connection: uses HTTP connection (evidence: `tornado/simple_httpclient.py`)
- Simple HTTP client → HTTP messages: uses HTTP messages (evidence: `tornado/simple_httpclient.py`)
- Simple HTTP client → Stream I/O: uses streams (evidence: `tornado/simple_httpclient.py`)
- Simple HTTP client → Network utilities: uses networking (evidence: `tornado/simple_httpclient.py`)
- Simple HTTP client → HTTP client API: implements interface (evidence: `tornado/simple_httpclient.py`)
- Curl HTTP client → HTTP client API: implements interface (evidence: `tornado/curl_httpclient.py`)
- Curl HTTP client → Event loop: uses event loop (evidence: `tornado/curl_httpclient.py`)
- Authentication → HTTP client API: makes HTTP requests (evidence: `tornado/auth.py`)
- Authentication → Request handlers: uses web framework (evidence: `tornado/auth.py`)
- Templates → Encoding utilities: uses escaping (evidence: `tornado/template.py`)
- Localization → Encoding utilities: uses escaping (evidence: `tornado/locale.py`)
- Localization → Logging: uses logging (evidence: `tornado/locale.py`)
- HTTP client API → Configuration options: uses options (evidence: `tornado/httpclient.py`)
