# blanketsucks/async-web-framework architecture

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

- Interactive diagram: https://gitdiagram.com/blanketsucks/async-web-framework
- Repository: https://github.com/blanketsucks/async-web-framework

## Overview

Subway is an asynchronous Python web framework. Its principal workflow accepts an HTTP connection, constructs a request, resolves a route and runs the application callback, then converts and sends a response. The README documents request/response middleware and a distinct WebSocket callback path. The graph also preserves framework extensions, static files, sessions, models, and client-side HTTP support. Some subsystem links rely on the README or SOURCE INDEX references; unsampled code does not establish further runtime call order.

Main entry points: [`subway/app.py`](https://github.com/blanketsucks/async-web-framework/blob/master/subway/app.py) (Application), [`subway/request.py`](https://github.com/blanketsucks/async-web-framework/blob/master/subway/request.py) (Request Parsing), [`subway/workers.py`](https://github.com/blanketsucks/async-web-framework/blob/master/subway/workers.py) (Connection Worker), [`subway/response.py`](https://github.com/blanketsucks/async-web-framework/blob/master/subway/response.py) (Response Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Request Runtime"]
  node_server["Async Server<br/>[__init__.py]"]
  node_worker["Connection Worker<br/>[workers.py]"]
  node_application["Application<br/>[app.py]"]
  node_routing["Route Matching<br/>[router.py]"]
  node_route_objects["Routes and Middleware<br/>[objects.py]"]
end

subgraph group_http["HTTP Primitives"]
  node_request["Request Parsing<br/>[request.py]"]
  node_response["Response Types<br/>[response.py]"]
  node_response_helpers["HTTP Status Responses<br/>[responses.py]"]
  node_streams["Async Streams<br/>[streams.py]"]
  node_http_protocol["HTTP Protocol Types<br/>[abc.py]"]
  node_headers_cookies["Headers and Cookies<br/>[headers.py]"]
  node_cookies["Cookie Handling<br/>[cookies.py]"]
  node_files["File Responses<br/>[files.py]"]
  node_url["URL Handling<br/>[url.py]"]
end

subgraph group_features["Framework Features"]
  node_websocket["WebSocket Frames<br/>[enums.py]"]
  node_views_resources["Views and Resources<br/>[views.py]"]
  node_models["Data Models<br/>[fields.py]"]
  node_sessions["Server Sessions<br/>[sessions.py]"]
  node_static["Static Files<br/>[staticfiles.py]"]
end

subgraph group_integrations["Extensions and Clients"]
  node_sqlalchemy_results["SQLAlchemy Results<br/>[results.py]"]
  node_sqlalchemy_schemas["SQLAlchemy Schemas<br/>[schemas.py]"]
  node_http_client["HTTP Client Sessions<br/>[sessions.py]"]
  node_hooker["HTTP Transport<br/>[abc.py]"]
end

node_client(("HTTP Client"))

node_client -->|"sends request"| node_server
node_server -->|"serves connections"| node_worker
node_worker -->|"constructs request"| node_request
node_worker -->|"dispatches request"| node_application
node_application -->|"resolves route"| node_routing
node_routing -->|"returns route"| node_route_objects
node_application -->|"runs callback"| node_request
node_application -->|"converts result"| node_response
node_application -->|"handles HTTP errors"| node_response_helpers
node_request -->|"reads body"| node_streams
node_request -->|"parses URL"| node_url
node_request -->|"uses headers"| node_headers_cookies
node_request -->|"reads cookies"| node_cookies
node_response -->|"serves files"| node_files
node_response -->|"sets cookies"| node_cookies
node_worker -.->|"handles WebSocket"| node_websocket
node_application -->|"registers views"| node_views_resources
node_application -->|"supports sessions"| node_sessions
node_application -->|"configures static files"| node_static
node_sqlalchemy_results -->|"uses schemas"| node_sqlalchemy_schemas
node_http_client -->|"creates transport"| node_hooker
node_hooker -->|"uses streams"| node_streams
node_models -.->|"integrates models"| node_sqlalchemy_results

click node_server "https://github.com/blanketsucks/async-web-framework/blob/master/subway/server/__init__.py"
click node_worker "https://github.com/blanketsucks/async-web-framework/blob/master/subway/workers.py"
click node_application "https://github.com/blanketsucks/async-web-framework/blob/master/subway/app.py"
click node_routing "https://github.com/blanketsucks/async-web-framework/blob/master/subway/router.py"
click node_route_objects "https://github.com/blanketsucks/async-web-framework/blob/master/subway/objects.py"
click node_request "https://github.com/blanketsucks/async-web-framework/blob/master/subway/request.py"
click node_response "https://github.com/blanketsucks/async-web-framework/blob/master/subway/response.py"
click node_response_helpers "https://github.com/blanketsucks/async-web-framework/blob/master/subway/responses.py"
click node_streams "https://github.com/blanketsucks/async-web-framework/blob/master/subway/streams.py"
click node_http_protocol "https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/abc.py"
click node_headers_cookies "https://github.com/blanketsucks/async-web-framework/blob/master/subway/headers.py"
click node_cookies "https://github.com/blanketsucks/async-web-framework/blob/master/subway/cookies.py"
click node_files "https://github.com/blanketsucks/async-web-framework/blob/master/subway/files.py"
click node_url "https://github.com/blanketsucks/async-web-framework/blob/master/subway/url.py"
click node_websocket "https://github.com/blanketsucks/async-web-framework/blob/master/subway/websockets/enums.py"
click node_views_resources "https://github.com/blanketsucks/async-web-framework/blob/master/subway/views.py"
click node_models "https://github.com/blanketsucks/async-web-framework/blob/master/subway/models/fields.py"
click node_sessions "https://github.com/blanketsucks/async-web-framework/blob/master/subway/sessions.py"
click node_static "https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/staticfiles.py"
click node_sqlalchemy_results "https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/sqlalchemy/results.py"
click node_sqlalchemy_schemas "https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/sqlalchemy/schemas.py"
click node_http_client "https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/sessions.py"
click node_hooker "https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/abc.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_server,node_worker,node_application,node_routing,node_route_objects,node_client toneBlue
class node_request,node_response,node_response_helpers,node_streams,node_http_protocol,node_headers_cookies,node_cookies,node_files,node_url toneAmber
class node_websocket,node_views_resources,node_models,node_sessions,node_static toneMint
class node_sqlalchemy_results,node_sqlalchemy_schemas,node_http_client,node_hooker toneRose
```

## Components

### Request Runtime

- [Async Server](https://github.com/blanketsucks/async-web-framework/blob/master/subway/server/__init__.py): `subway/server/__init__.py`
- [Connection Worker](https://github.com/blanketsucks/async-web-framework/blob/master/subway/workers.py): `subway/workers.py`
- [Application](https://github.com/blanketsucks/async-web-framework/blob/master/subway/app.py): `subway/app.py`
- [Route Matching](https://github.com/blanketsucks/async-web-framework/blob/master/subway/router.py): `subway/router.py`
- [Routes and Middleware](https://github.com/blanketsucks/async-web-framework/blob/master/subway/objects.py): `subway/objects.py`

### HTTP Primitives

- [Request Parsing](https://github.com/blanketsucks/async-web-framework/blob/master/subway/request.py): `subway/request.py`
- [Response Types](https://github.com/blanketsucks/async-web-framework/blob/master/subway/response.py): `subway/response.py`
- [HTTP Status Responses](https://github.com/blanketsucks/async-web-framework/blob/master/subway/responses.py): `subway/responses.py`
- [Async Streams](https://github.com/blanketsucks/async-web-framework/blob/master/subway/streams.py): `subway/streams.py`
- [HTTP Protocol Types](https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/abc.py): `subway/http/abc.py`
- [Headers and Cookies](https://github.com/blanketsucks/async-web-framework/blob/master/subway/headers.py): `subway/headers.py`
- [Cookie Handling](https://github.com/blanketsucks/async-web-framework/blob/master/subway/cookies.py): `subway/cookies.py`
- [File Responses](https://github.com/blanketsucks/async-web-framework/blob/master/subway/files.py): `subway/files.py`
- [URL Handling](https://github.com/blanketsucks/async-web-framework/blob/master/subway/url.py): `subway/url.py`

### Framework Features

- [WebSocket Frames](https://github.com/blanketsucks/async-web-framework/blob/master/subway/websockets/enums.py): `subway/websockets/enums.py`
- [Views and Resources](https://github.com/blanketsucks/async-web-framework/blob/master/subway/views.py): `subway/views.py`
- [Data Models](https://github.com/blanketsucks/async-web-framework/blob/master/subway/models/fields.py): `subway/models/fields.py`
- [Server Sessions](https://github.com/blanketsucks/async-web-framework/blob/master/subway/sessions.py): `subway/sessions.py`
- [Static Files](https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/staticfiles.py): `subway/extensions/staticfiles.py`

### Extensions and Clients

- [SQLAlchemy Results](https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/sqlalchemy/results.py): `subway/extensions/sqlalchemy/results.py`
- [SQLAlchemy Schemas](https://github.com/blanketsucks/async-web-framework/blob/master/subway/extensions/sqlalchemy/schemas.py): `subway/extensions/sqlalchemy/schemas.py`
- [HTTP Client Sessions](https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/sessions.py): `subway/http/sessions.py`
- [HTTP Transport](https://github.com/blanketsucks/async-web-framework/blob/master/subway/http/abc.py): `subway/http/abc.py`

### Other components

- **HTTP Client**

## Connections

- HTTP Client → Async Server: sends request
- Async Server → Connection Worker: serves connections (evidence: `subway/workers.py`)
- Connection Worker → Request Parsing: constructs request (evidence: `subway/workers.py`)
- Connection Worker → Application: dispatches request (evidence: `subway/workers.py`)
- Application → Route Matching: resolves route (evidence: `subway/app.py`)
- Route Matching → Routes and Middleware: returns route (evidence: `subway/router.py`)
- Application → Request Parsing: runs callback (evidence: `subway/app.py`)
- Application → Response Types: converts result (evidence: `subway/app.py`)
- Application → HTTP Status Responses: handles HTTP errors (evidence: `subway/app.py`)
- Request Parsing → Async Streams: reads body (evidence: `subway/request.py`)
- Request Parsing → URL Handling: parses URL (evidence: `subway/request.py`)
- Request Parsing → Headers and Cookies: uses headers (evidence: `subway/request.py`)
- Request Parsing → Cookie Handling: reads cookies (evidence: `subway/request.py`)
- Response Types → File Responses: serves files (evidence: `subway/response.py`)
- Response Types → Cookie Handling: sets cookies (evidence: `subway/response.py`)
- Connection Worker → WebSocket Frames: handles WebSocket
- Application → Views and Resources: registers views (evidence: `subway/app.py`)
- Application → Server Sessions: supports sessions (evidence: `subway/sessions.py`)
- Application → Static Files: configures static files (evidence: `subway/extensions/staticfiles.py`)
- SQLAlchemy Results → SQLAlchemy Schemas: uses schemas (evidence: `subway/extensions/sqlalchemy/types.py`)
- HTTP Client Sessions → HTTP Transport: creates transport (evidence: `subway/http/sessions.py`)
- HTTP Transport → Async Streams: uses streams (evidence: `subway/http/abc.py`)
- Data Models → SQLAlchemy Results: integrates models
