# encode/uvicorn architecture

> Architecture diagram of the GitHub repository encode/uvicorn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/encode/uvicorn
- Repository: https://github.com/encode/uvicorn

## Overview

##### Main Components

a) Core Server Components:
- ASGI Server Interface (main entry point)
- Protocol Handlers
- HTTP Protocols (h11_impl, httptools_impl)
- WebSocket Protocols (websockets_impl, wsproto_impl)
- Server Lifecycle Manager
- Supervisors (multiprocess, reload mechanisms)

b) Event Loop Handlers:
- AsyncIO Loop
- UvLoop (optional)
- Auto Detection Layer

c) Middleware Layer:
- ASGI 2.0 Compatibility
- Proxy Headers
- Message Logger
- WSGI Compatibility

##### Relationships and Flow

- Incoming HTTP/WebSocket requests → Protocol Handlers
- Protocol Handlers → ASGI Application Interface
- ASGI Interface ↔ User Application
- Event Loop Controllers → Server Core
- Middleware Layer between Protocol Handlers and ASGI Interface

##### Specific Implementation Details

- Blue rectangles: Core server components
- Green rectangles: Protocol implementations
- Yellow diamonds: Middleware components
- Purple ovals: Event loop handlers
- Orange hexagons: Supervisor components

##### Key Architectural Patterns to Highlight

a) Plugin Architecture:
- How different protocol implementations (HTTP/WebSocket) can be swapped
- Event loop alternatives (asyncio/uvloop)

b) Middleware Chain:
- Demonstrate the middleware stack's flow
- Optional middleware components

##### Component Relationships

- Request flow: Client → Protocol Handlers → Middleware → ASGI App
- Response flow: ASGI App → Middleware → Protocol Handlers → Client
- Control flow: Supervisors → Server Core
- Configuration flow: Config → Components

##### Additional Elements

Special features:
- Lifespan management components
- Multiple worker support
- Reload mechanisms
- SSL/TLS handling

##### Notes for Implementation

- Keep the main flow clear and centered
- Related components (all protocols together, all middleware together)
- Version compatibility notes
- Integration points with external systems

Remember to maintain a balance between showing enough detail to understand the system's architecture while not overwhelming the viewer with implementation-specific details that might change between versions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        C[Client Requests]
    end

    subgraph "Server Layer"
        ASGI["ASGI Server Interface"]:::core
        SC["Server Core"]:::core
        CFG["Configuration Handler"]:::core
    end

    subgraph "Protocol Layer"
        direction TB
        PH["Protocol Handlers"]:::protocol
        subgraph "HTTP Protocols"
            direction TB
            H11["H11 Implementation"]:::protocol
            HT["HTTPTools Implementation"]:::protocol
        end
        subgraph "WebSocket Protocols"
            direction TB
            WS["WebSockets Implementation"]:::protocol
            WSP["WSProto Implementation"]:::protocol
        end
    end

    subgraph "Middleware Layer"
        direction TB
        ASGI2["ASGI 2.0 Compatibility"]:::middleware
        PXH["Proxy Headers"]:::middleware
        ML["Message Logger"]:::middleware
        WSGI["WSGI Compatibility"]:::middleware
    end

    subgraph "Event Loop Layer"
        direction TB
        AD["Auto Detection"]:::eventloop
        AIOL["AsyncIO Loop"]:::eventloop
        UVL["UvLoop"]:::eventloop
    end

    subgraph "Supervisor Layer"
        direction TB
        BR["Base Reload"]:::supervisor
        MP["Multiprocess"]:::supervisor
        SR["Stat Reload"]:::supervisor
        WF["Watch Files Reload"]:::supervisor
    end

    subgraph "Lifespan Layer"
        direction TB
        LC["Lifespan Core"]:::lifespan
        LON["Lifespan On"]:::lifespan
        LOFF["Lifespan Off"]:::lifespan
    end

    C --> PH
    PH --> |HTTP| H11 & HT
    PH --> |WebSocket| WS & WSP
    H11 & HT & WS & WSP --> ASGI2
    ASGI2 --> PXH --> ML --> WSGI
    WSGI --> ASGI
    ASGI --> SC
    CFG --> SC
    AD --> AIOL & UVL
    AIOL & UVL --> SC
    BR & MP & SR & WF --> SC
    LC --> LON & LOFF
    LC --> SC

    classDef core fill:#2374f7,stroke:#000,stroke-width:2px,color:#fff
    classDef protocol fill:#4CAF50,stroke:#000,stroke-width:2px,color:#fff
    classDef middleware fill:#FFD700,stroke:#000,stroke-width:2px,color:#000
    classDef eventloop fill:#9C27B0,stroke:#000,stroke-width:2px,color:#fff
    classDef supervisor fill:#FF9800,stroke:#000,stroke-width:2px,color:#fff
    classDef lifespan fill:#795548,stroke:#000,stroke-width:2px,color:#fff

    click ASGI "https://github.com/encode/uvicorn/blob/master/uvicorn/main.py"
    click SC "https://github.com/encode/uvicorn/blob/master/uvicorn/server.py"
    click CFG "https://github.com/encode/uvicorn/blob/master/uvicorn/config.py"
    click H11 "https://github.com/encode/uvicorn/blob/master/uvicorn/protocols/http/h11_impl.py"
    click HT "https://github.com/encode/uvicorn/blob/master/uvicorn/protocols/http/httptools_impl.py"
    click WS "https://github.com/encode/uvicorn/blob/master/uvicorn/protocols/websockets/websockets_impl.py"
    click WSP "https://github.com/encode/uvicorn/blob/master/uvicorn/protocols/websockets/wsproto_impl.py"
    click AIOL "https://github.com/encode/uvicorn/blob/master/uvicorn/loops/asyncio.py"
    click UVL "https://github.com/encode/uvicorn/blob/master/uvicorn/loops/uvloop.py"
    click AD "https://github.com/encode/uvicorn/blob/master/uvicorn/loops/auto.py"
    click ASGI2 "https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/asgi2.py"
    click PXH "https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py"
    click ML "https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/message_logger.py"
    click WSGI "https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/wsgi.py"
    click BR "https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/basereload.py"
    click MP "https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/multiprocess.py"
    click SR "https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/statreload.py"
    click WF "https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/watchfilesreload.py"
    click LC "https://github.com/encode/uvicorn/blob/master/uvicorn/lifespan/__init__.py"
    click LON "https://github.com/encode/uvicorn/blob/master/uvicorn/lifespan/on.py"
    click LOFF "https://github.com/encode/uvicorn/blob/master/uvicorn/lifespan/off.py"
```
