# kludex/starlette architecture

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

- Interactive diagram: https://gitdiagram.com/kludex/starlette
- Repository: https://github.com/kludex/starlette

## Overview

##### Project type and purpose
- Starlette is a lightweight, modular ASGI framework/toolkit for building async web services in Python. It provides core HTTP routing, middleware, WebSocket support, background tasks, templating, static-file serving, and a built-in test client.

##### File structure
- Top-level directories:
- `starlette/` contains the production library code, organized by component (applications, routing, requests, responses, middleware, websockets, etc.).
- `tests/` contains comprehensive unit tests for each component.
- `docs/` and `mkdocs.yml` define the project documentation.
- `.github/` and `scripts/` hold CI/CD workflows, release scripts, linting and test commands.
- `pyproject.toml` and `requirements.txt` list core and optional dependencies.

- Key patterns:
- Chain-of-responsibility pattern for middleware (in `starlette/middleware/*`).
- Central application/router in `starlette/applications.py` orchestrating request flow.
- Separation between the ASGI server interface (user’s Uvicorn/Daphne) and the Starlette app.

##### README for additional insights
- Confirms the ASGI entrypoint, optional dependencies, and pluggable components.
- Highlights modularity: every component (responses, forms, staticfiles, sessions) can be used standalone.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    ASGI_SERVER["ASGI Server (e.g., Uvicorn)"]:::external

    %% Core Application
    subgraph "Core Library" 
        APPLICATION["Starlette Application"]:::core
    end

    ASGI_SERVER -->|"invoke __call__(scope,receive,send)"| APPLICATION

    %% Middleware Stack
    subgraph "Middleware Stack" 
        BASE_MW["BaseMiddleware"]:::middleware
        CORS_MW["CORSMiddleware"]:::middleware
        GZIP_MW["GZipMiddleware"]:::middleware
        HTTPS_MW["HTTPSRedirectMiddleware"]:::middleware
        SESSION_MW["SessionMiddleware"]:::middleware
        ERRORS_MW["ErrorHandlingMiddleware"]:::middleware
        EXCEPT_MW["ExceptionsMiddleware"]:::middleware
        TRUSTEDHOST_MW["TrustedHostMiddleware"]:::middleware
        WSGI_MW["WSGIMiddleware"]:::middleware
    end

    APPLICATION -->|enter stack| BASE_MW --> CORS_MW --> GZIP_MW --> HTTPS_MW --> SESSION_MW --> ERRORS_MW --> EXCEPT_MW --> TRUSTEDHOST_MW --> WSGI_MW

    %% Router & Endpoints
    subgraph "Routing Layer"
        ROUTER["Router (starlette/routing.py)"]:::router
        ENDPOINTS["Endpoints (starlette/endpoints.py)"]:::router
    end

    WSGI_MW -->|dispatch| ROUTER --> ENDPOINTS

    %% Request/Response Models
    subgraph "Data Models"
        REQUEST["Request (starlette/requests.py)"]:::model
        RESPONSE["Response (starlette/responses.py)"]:::model
    end

    ENDPOINTS -->|"produce"| RESPONSE
    ENDPOINTS -->|"consume"| REQUEST

    %% Background Tasks
    BACKGROUND["Background Task Manager (starlette/background.py)"]:::service
    ENDPOINTS -->|"schedule"| BACKGROUND

    %% Static Files & Templates
    subgraph "Static & Templates"
        STATICFILES["StaticFiles (starlette/staticfiles.py)"]:::service
        TEMPLATING["Templating (starlette/templating.py)"]:::service
    end

    ROUTER -->|static route| STATICFILES
    ENDPOINTS -->|render| TEMPLATING

    %% Optional Integrations
    subgraph "Optional Integrations"
        JINJA["Jinja2 Integration"]:::optional
        TESTCLIENT["HTTPX TestClient"]:::optional
        MULTIPART["MultipartParser"]:::optional
        ITS_DANGEROUS["ItsDangerous Signing"]:::optional
    end

    TEMPLATING --> JINJA
    APPLICATION --> TESTCLIENT
    SESSION_MW --> ITS_DANGEROUS
    ENDPOINTS --> MULTIPART

    %% Concurrency / ASGI Types
    subgraph "Concurrency & Types"
        CONCURRENCY["Concurrency (anyio/asyncio)"]:::util
        ASGI_TYPES["ASGI Types (starlette/types.py)"]:::util
    end

    APPLICATION --> CONCURRENCY
    APPLICATION --> ASGI_TYPES

    %% Exceptions & Utilities
    subgraph "Exceptions & Utilities"
        EXCEPTIONS["Core Exceptions (starlette/exceptions.py)"]:::util
        HANDLER["Exception Handler (starlette/_exception_handler.py)"]:::util
        UTILS["Utilities (starlette/_utils.py)"]:::util
    end

    APPLICATION --> EXCEPTIONS --> HANDLER --> UTILS

    %% Configuration & Data Structures
    subgraph "Configuration & Data"
        CONFIG["Config Loader (starlette/config.py)"]:::util
        DATASTRUCT["Datastructures (starlette/datastructures.py)"]:::util
    end

    APPLICATION --> CONFIG
    APPLICATION --> DATASTRUCT

    %% Convertors & Schemas
    subgraph "URL Convertors & Schemas"
        CONVERTORS["Path Convertors (starlette/convertors.py)"]:::util
        SCHEMAS["Schemas (starlette/schemas.py)"]:::util
    end

    ROUTER --> CONVERTORS
    ROUTER --> SCHEMAS

    %% Status Codes
    STATUS["Status Codes (starlette/status.py)"]:::util
    RESPONSE --> STATUS

    %% External Services
    subgraph "External Services"
        DATABASE["Database/Third-party API"]:::external
    end

    ENDPOINTS -->|"calls"| DATABASE

    %% Click Events
    click APPLICATION "https://github.com/kludex/starlette/blob/master/starlette/applications.py"
    click BASE_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/base.py"
    click CORS_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/cors.py"
    click GZIP_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/gzip.py"
    click HTTPS_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/httpsredirect.py"
    click SESSION_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/sessions.py"
    click ERRORS_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/errors.py"
    click EXCEPT_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/exceptions.py"
    click TRUSTEDHOST_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/trustedhost.py"
    click WSGI_MW "https://github.com/kludex/starlette/blob/master/starlette/middleware/wsgi.py"
    click ROUTER "https://github.com/kludex/starlette/blob/master/starlette/routing.py"
    click ENDPOINTS "https://github.com/kludex/starlette/blob/master/starlette/endpoints.py"
    click REQUEST "https://github.com/kludex/starlette/blob/master/starlette/requests.py"
    click RESPONSE "https://github.com/kludex/starlette/blob/master/starlette/responses.py"
    click BACKGROUND "https://github.com/kludex/starlette/blob/master/starlette/background.py"
    click STATICFILES "https://github.com/kludex/starlette/blob/master/starlette/staticfiles.py"
    click TEMPLATING "https://github.com/kludex/starlette/blob/master/starlette/templating.py"
    click TESTCLIENT "https://github.com/kludex/starlette/blob/master/starlette/testclient.py"
    click MULTIPART "https://github.com/kludex/starlette/blob/master/starlette/formparsers.py"
    click ITS_DANGEROUS "https://github.com/kludex/starlette/blob/master/starlette/middleware/sessions.py"
    click CONCURRENCY "https://github.com/kludex/starlette/blob/master/starlette/concurrency.py"
    click ASGI_TYPES "https://github.com/kludex/starlette/blob/master/starlette/types.py"
    click EXCEPTIONS "https://github.com/kludex/starlette/blob/master/starlette/exceptions.py"
    click HANDLER "https://github.com/kludex/starlette/blob/master/starlette/_exception_handler.py"
    click UTILS "https://github.com/kludex/starlette/blob/master/starlette/_utils.py"
    click CONFIG "https://github.com/kludex/starlette/blob/master/starlette/config.py"
    click DATASTRUCT "https://github.com/kludex/starlette/blob/master/starlette/datastructures.py"
    click CONVERTORS "https://github.com/kludex/starlette/blob/master/starlette/convertors.py"
    click SCHEMAS "https://github.com/kludex/starlette/blob/master/starlette/schemas.py"
    click STATUS "https://github.com/kludex/starlette/blob/master/starlette/status.py"

    %% Styles
    classDef external fill:#ffe6e6,stroke:#cc0000,color:#660000
    classDef core fill:#e6f0ff,stroke:#0059b3,color:#003366
    classDef middleware fill:#e6ffe6,stroke:#009900,color:#004d00
    classDef router fill:#f0e6ff,stroke:#8000b3,color:#4d004d
    classDef model fill:#fff2cc,stroke:#b36b00,color:#804000
    classDef service fill:#ffe6cc,stroke:#b34700,color:#663300
    classDef optional fill:#e6ffe6,stroke:#339966,color:#004d33
    classDef util fill:#f2f2f2,stroke:#666666,color:#333333
```
