# sanic-org/sanic architecture

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

- Interactive diagram: https://gitdiagram.com/sanic-org/sanic
- Repository: https://github.com/sanic-org/sanic

## Overview

Sanic is a Python 3.10+ async web framework and HTTP server. The repo is organized around a runtime core, a protocol/server layer, and a set of application-facing abstractions for routing, request handling, and lifecycle management.

1. Core application object
The central boundary is `sanic.app.Sanic`, backed by mixins under `sanic/mixins/`. This is where an app accumulates configuration, routes, middleware, signals, listeners, static handlers, and extension state. Most user-facing APIs ultimately register into this app object.

2. Request-to-response flow
Incoming traffic is converted into `sanic.request` objects, routed by `sanic.router`, passed through middleware and handlers, and returned as `sanic.response` objects. This is the main application execution path and the key diagram flow for request processing.

3. Routing and view dispatch
Routing is split between route registration and route matching. `sanic.blueprints`, `sanic.blueprint_group`, and `sanic.views` add structure for grouping handlers, class-based views, and versioned/mounted route sets. The router and these abstractions define how URL paths map to callables.

4. Middleware, signals, listeners, and startup hooks
Cross-cutting behavior is implemented in separate subsystems: `sanic.middleware`, `sanic.signals`, `sanic/mixins/listeners.py`, and `sanic/mixins/startup.py`. These provide ordered request/response interception, event-style hooks, and application lifecycle callbacks.

5. Server and protocol layer
The lower layer lives in `sanic/server/` and `sanic/http/`. It handles socket setup, event loop integration, HTTP/1 processing, websockets, and TLS. The server layer is where application code is decoupled from transport concerns.

6. ASGI and deployment compatibility
`sanic.asgi` exposes ASGI compatibility so the framework can run under alternative ASGI servers. This makes the transport boundary explicit: the app can be served by Sanic’s own server stack or integrated into the broader ASGI ecosystem.

7. WebSocket and streaming support
WebSocket handling is first-class via `sanic/server/protocols/websocket_protocol.py` and `sanic/server/websockets/`. Streaming is also represented in `sanic/http/stream.py` and documented examples. These paths are separate from normal request/response handling and should be shown as specialized protocol flows.

8. CLI, worker lifecycle, and reload/daemon tooling
Operational control lives in `sanic/cli/` and `sanic/worker/`. This includes app loading, daemonization, inspector mode, process management, reloading, restarts, and multi-worker serving. The CLI is the entry point that bridges user configuration to runtime server startup.

9. Configuration, logging, and runtime behavior
`sanic.config`, `sanic/log.py`, and `sanic/logging/` centralize application settings and logging behavior. These modules influence server startup, debug/development mode, error reporting, and operational observability rather than request routing itself.

10. Error handling and HTTP utilities
Error translation is handled by `sanic.exceptions`, `sanic/errorpages.py`, and `sanic/handlers/error.py`. HTTP-specific helpers live in `sanic/http/constants.py`, `sanic/headers.py`, `sanic/cookies/`, and `sanic/handlers/content_range.py` / `directory.py`. These are support layers around the core request pipeline.

11. Static content and page rendering
Static file serving is built into the framework through `sanic/mixins/static.py`, `sanic/pages/`, and related handlers. This is a distinct boundary from dynamic routing because it resolves files/pages rather than executing app-defined handlers.

12. Type/model boundary and internal contracts
The `sanic/models/` and `sanic/types/` packages define typed interfaces for ASGI, protocol handlers, futures, server state, and shared context. These are internal contracts used to keep the server, app, and worker subsystems loosely coupled.

13. Documentation and developer portal
The repository includes a substantial docs system (`docs/` and `guide/`) plus a separate Sanic-powered guide web app under `guide/webapp/`. This is not part of the runtime framework, but it is a meaningful secondary application with its own display, endpoint, and worker layers.

14. Tests and examples as architecture validation
`tests/` exercises the framework across HTTP, ASGI, websockets, TLS, workers, static files, CLI, and reloader behavior. `examples/` demonstrates the supported integration patterns and is useful for understanding the intended subsystem boundaries and data flows.

Overall, the architecture is a layered async framework: CLI and workers boot the server; the server/protocol layer turns sockets into HTTP/WebSocket events; the app/router/middleware stack converts those events into handler execution; and response/error/static utilities shape the output back to the client.

Main entry points: [`sanic/app.py`](https://github.com/sanic-org/sanic/blob/main/sanic/app.py) (Sanic app), [`sanic/server`](https://github.com/sanic-org/sanic/tree/main/sanic/server) (Server), [`sanic/router.py`](https://github.com/sanic-org/sanic/blob/main/sanic/router.py) (Router), [`tests`](https://github.com/sanic-org/sanic/tree/main/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core framework"]
  node_sanic_app["Sanic app<br/>application core<br/>[app.py]"]
  node_sanic_mixins["App mixins<br/>app composition"]
  node_router["Router<br/>route matcher<br/>[router.py]"]
  node_request["Request"]
  node_response["Response"]
  node_blueprints["Blueprints<br/>route grouping<br/>[blueprints.py]"]
  node_views["Views<br/>[views.py]"]
  node_signals(("Signals<br/>event hooks<br/>[signals.py]"))
  node_middleware["Middleware<br/>interception<br/>[middleware.py]"]
  node_startup["Startup<br/>lifecycle hooks"]
end

subgraph group_runtime["Runtime stack"]
  node_server["Server"]
  node_protocols["Protocols"]
  node_http_layer["HTTP stack<br/>http processing"]
  node_websockets["WebSockets<br/>ws runtime"]
  node_worker["Workers<br/>process orchestration"]
  node_asgi["ASGI bridge<br/>compatibility layer<br/>[asgi.py]"]
end

subgraph group_ops["Operations"]
  node_cli["CLI<br/>command entrypoint"]
  node_config_log["Config & logging<br/>runtime settings<br/>[config.py]"]
end

subgraph group_docs["Documentation app"]
  node_guide_app["Guide app<br/>docs web app"]
  node_docs_site["Docs site<br/>documentation"]
end

subgraph group_validation["Validation"]
  node_tests["Tests<br/>validation suite"]
  node_examples["Examples<br/>usage samples"]
end

node_sanic_app -->|"composes"| node_sanic_mixins
node_sanic_app -->|"registers to"| node_router
node_sanic_app -->|"attaches"| node_middleware
node_sanic_app -->|"emits"| node_signals
node_sanic_app -->|"boots with"| node_startup
node_router -->|"dispatches to"| node_views
node_router -->|"routes"| node_request
node_request -->|"yields"| node_response
node_middleware -->|"wraps"| node_request
node_middleware -->|"wraps"| node_response
node_server -->|"drives"| node_protocols
node_protocols -->|"uses"| node_http_layer
node_protocols -->|"upgrades to"| node_websockets
node_server -->|"managed by"| node_worker
node_cli -->|"starts"| node_server
node_cli -->|"orchestrates"| node_worker
node_config_log -->|"configures"| node_cli
node_config_log -->|"configures"| node_server
node_asgi -->|"adapts"| node_sanic_app
node_guide_app -->|"uses framework"| node_sanic_app
node_docs_site -.->|"references"| node_guide_app
node_tests -.->|"verifies"| node_sanic_app
node_tests -.->|"verifies"| node_server
node_tests -.->|"verifies"| node_asgi
node_examples -.->|"demonstrates"| node_router
node_examples -.->|"demonstrates"| node_websockets

click node_sanic_app "https://github.com/sanic-org/sanic/blob/main/sanic/app.py"
click node_sanic_mixins "https://github.com/sanic-org/sanic/tree/main/sanic/mixins"
click node_router "https://github.com/sanic-org/sanic/blob/main/sanic/router.py"
click node_request "https://github.com/sanic-org/sanic/tree/main/sanic/request"
click node_response "https://github.com/sanic-org/sanic/tree/main/sanic/response"
click node_blueprints "https://github.com/sanic-org/sanic/blob/main/sanic/blueprints.py"
click node_views "https://github.com/sanic-org/sanic/blob/main/sanic/views.py"
click node_signals "https://github.com/sanic-org/sanic/blob/main/sanic/signals.py"
click node_middleware "https://github.com/sanic-org/sanic/blob/main/sanic/middleware.py"
click node_startup "https://github.com/sanic-org/sanic/tree/main/sanic/startup"
click node_server "https://github.com/sanic-org/sanic/tree/main/sanic/server"
click node_protocols "https://github.com/sanic-org/sanic/tree/main/sanic/server/protocols"
click node_http_layer "https://github.com/sanic-org/sanic/tree/main/sanic/http"
click node_websockets "https://github.com/sanic-org/sanic/tree/main/sanic/server/websockets"
click node_worker "https://github.com/sanic-org/sanic/tree/main/sanic/worker"
click node_cli "https://github.com/sanic-org/sanic/tree/main/sanic/cli"
click node_config_log "https://github.com/sanic-org/sanic/blob/main/sanic/config.py"
click node_asgi "https://github.com/sanic-org/sanic/blob/main/sanic/asgi.py"
click node_guide_app "https://github.com/sanic-org/sanic/tree/main/guide/webapp"
click node_docs_site "https://github.com/sanic-org/sanic/tree/main/docs"
click node_tests "https://github.com/sanic-org/sanic/tree/main/tests"
click node_examples "https://github.com/sanic-org/sanic/tree/main/examples"

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_sanic_app,node_sanic_mixins,node_router,node_request,node_response,node_blueprints,node_views,node_signals,node_middleware,node_startup toneBlue
class node_server,node_protocols,node_http_layer,node_websockets,node_worker,node_asgi toneAmber
class node_cli,node_config_log toneMint
class node_guide_app,node_docs_site toneRose
class node_tests,node_examples toneIndigo
```

## Components

### Core framework

Application, routing, request/response, and lifecycle abstractions.

- [Sanic app](https://github.com/sanic-org/sanic/blob/main/sanic/app.py): application core · Central application object that collects routes, middleware, listeners, signals, and extensions. · `sanic/app.py`
- [App mixins](https://github.com/sanic-org/sanic/tree/main/sanic/mixins): app composition · Reusable behaviors for routes, middleware, listeners, startup, static content, commands, and exceptions. · `sanic/mixins`
- [Router](https://github.com/sanic-org/sanic/blob/main/sanic/router.py): route matcher · Maps incoming paths and methods to handlers and named routes. · `sanic/router.py`
- [Request](https://github.com/sanic-org/sanic/tree/main/sanic/request): request model · HTTP request parsing and request-scoped data structures. · `sanic/request`
- [Response](https://github.com/sanic-org/sanic/tree/main/sanic/response): response model · Response construction and convenience APIs for outbound HTTP results. · `sanic/response`
- [Blueprints](https://github.com/sanic-org/sanic/blob/main/sanic/blueprints.py): route grouping · Grouped and reusable route registration for modular applications. · `sanic/blueprints.py`
- [Views](https://github.com/sanic-org/sanic/blob/main/sanic/views.py): class-based views · Class-based handler dispatch and view composition. · `sanic/views.py`
- [Signals](https://github.com/sanic-org/sanic/blob/main/sanic/signals.py): event hooks · Application events and signal dispatch for cross-cutting coordination. · `sanic/signals.py`
- [Middleware](https://github.com/sanic-org/sanic/blob/main/sanic/middleware.py): interception · Ordered request and response interception hooks. · `sanic/middleware.py`
- [Startup](https://github.com/sanic-org/sanic/tree/main/sanic/startup): lifecycle hooks · Application initialization and startup error handling. · `sanic/startup`

### Runtime stack

Server, protocol, worker, and transport handling.

- [Server](https://github.com/sanic-org/sanic/tree/main/sanic/server): runtime server · Async server orchestration, event loop integration, runners, and socket setup. · `sanic/server`
- [Protocols](https://github.com/sanic-org/sanic/tree/main/sanic/server/protocols): transport protocols · HTTP and websocket protocol adapters for the server layer. · `sanic/server/protocols`
- [HTTP stack](https://github.com/sanic-org/sanic/tree/main/sanic/http): http processing · HTTP/1, HTTP/3, streaming, TLS, and related transport utilities. · `sanic/http`
- [WebSockets](https://github.com/sanic-org/sanic/tree/main/sanic/server/websockets): ws runtime · WebSocket connection, framing, and implementation support. · `sanic/server/websockets`
- [Workers](https://github.com/sanic-org/sanic/tree/main/sanic/worker): process orchestration · Multi-worker serving, reload, restarts, daemon mode, and process management. · `sanic/worker`
- [ASGI bridge](https://github.com/sanic-org/sanic/blob/main/sanic/asgi.py): compatibility layer · ASGI compatibility boundary for alternative deployment environments. · `sanic/asgi.py`

### Operations

CLI, configuration, logging, and startup behavior.

- [CLI](https://github.com/sanic-org/sanic/tree/main/sanic/cli): command entrypoint · Command-line app loading and runtime control entrypoints. · `sanic/cli`
- [Config & logging](https://github.com/sanic-org/sanic/blob/main/sanic/config.py): runtime settings · Configuration, logging setup, log formatting, and operational defaults. · `sanic/config.py`

### Documentation app

Repository docs plus the Sanic-powered guide site.

- [Guide app](https://github.com/sanic-org/sanic/tree/main/guide/webapp): docs web app · Sanic-powered documentation web application for the project guide. · `guide/webapp`
- [Docs site](https://github.com/sanic-org/sanic/tree/main/docs): documentation · Static documentation, guides, release notes, and contributor docs. · `docs`

### Validation

Tests and examples that exercise framework boundaries.

- [Tests](https://github.com/sanic-org/sanic/tree/main/tests): validation suite · Repository-wide verification of HTTP, ASGI, websockets, workers, CLI, static files, and routing. · `tests`
- [Examples](https://github.com/sanic-org/sanic/tree/main/examples): usage samples · Runnable examples demonstrating app patterns, deployment, streaming, websockets, and static serving. · `examples`

## Connections

- Sanic app → App mixins: composes · The app is built from mixin-based capabilities.
- Sanic app → Router: registers to · Routes and named paths are accumulated into the router.
- Sanic app → Middleware: attaches · Middleware is registered on the app and applied during requests.
- Sanic app → Signals: emits · The app exposes signal/event hooks for extensions and lifecycle coordination.
- Sanic app → Startup: boots with · Startup routines initialize the application and validate readiness.
- Router → Views: dispatches to · Matched routes may resolve to class-based view handlers.
- Router → Request: routes · Routing operates on parsed request information.
- Request → Response: yields · Handlers transform requests into response objects.
- Middleware → Request: wraps · Request middleware can inspect and mutate inbound requests.
- Middleware → Response: wraps · Response middleware can adjust outbound responses.
- Server → Protocols: drives · The async server hosts HTTP and websocket protocol adapters.
- Protocols → HTTP stack: uses · HTTP protocol handling relies on HTTP parsing and streaming utilities.
- Protocols → WebSockets: upgrades to · WebSocket protocol handling delegates to websocket runtime support.
- Server → Workers: managed by · Serving can be coordinated through worker, reload, and process-management subsystems.
- CLI → Server: starts · The CLI is the primary entrypoint for launching the server stack.
- CLI → Workers: orchestrates · CLI commands delegate to worker lifecycle and process management.
- Config & logging → CLI: configures · Configuration and logging affect command behavior and runtime startup.
- Config & logging → Server: configures · Runtime settings influence server behavior and observability.
- ASGI bridge → Sanic app: adapts · ASGI compatibility exposes the app to alternative servers.
- Guide app → Sanic app: uses framework · The guide web application is itself built on Sanic.
- Docs site → Guide app: references · The docs and guide materials explain and support the guide application.
- Tests → Sanic app: verifies · Tests cover app behavior, routing, middleware, and lifecycle boundaries.
- Tests → Server: verifies · Tests exercise server, protocol, TLS, and worker behaviors.
- Tests → ASGI bridge: verifies · Tests cover ASGI compatibility paths.
- Examples → Router: demonstrates · Examples show route registration and dispatch patterns.
- Examples → WebSockets: demonstrates · Examples include WebSocket usage and streaming patterns.
