# neoteroi/blacksheep architecture

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

- Interactive diagram: https://gitdiagram.com/neoteroi/blacksheep
- Repository: https://github.com/neoteroi/blacksheep

## Overview

##### Project type and purpose
- BlackSheep is an asynchronous Python web framework (an ASGI library)
plus an optional HTTP client.
- It is not a monolithic application, but a library intended to be embedded
in user code and run under an ASGI server (e.g. uvicorn or hypercorn).
- Key features (from README): routing, middleware pipeline, dependency injection,
authentication/authorization, OpenAPI generation, WebSockets, SSE, static‐file
serving, templating (Jinja2), sessions, plus an HTTP client.

##### File structure
- Top-level “blacksheep” package subdivided into:
– server: ASGI adapter, application entrypoint, routing, controllers,
authentication (cookie, JWT, OIDC), authorization policies, CORS, CSRF,
compression, dataprotection, diagnostics, files (static/dynamic), headers,
OpenAPI generators (v3, UI), process management, rendering, redirects,
remote forwarding, SSE, WebSocket, responses, security (HSTS), sessions
– client: connection pool, cookies, session, exceptions
– common: async file utilities, type definitions
– settings: DI for JSON/HTML settings
– testing: TestClient, message simulators, helpers
– utils: async helpers, metadata, timing
– Cython/pyx modules (.pxd/.pyx) for performance‐critical code (URL, headers,
messages, scribe, contents, cookies, exceptions)
- Other directories:
– itests: integration test apps and fixtures
– perf: benchmark apps and reporters
– tests: unit tests, example apps and templates
– project config (pyproject.toml, setup.py, Makefile, CI workflows)

##### Extract architecture insights from README
- Framework sits behind an ASGI server: exposes an ASGI “app” callable.
- On each request: ASGI server → BlackSheep ASGI adapter → middleware pipeline →
routing → controller or handler function → produce Response.
- Automatic parameter binding and DI feed handlers.
- Authentication & authorization plugged as middleware/strategies.
- Static files, OpenAPI docs, SSE/WebSocket, templating are “modules” wired
into the pipeline.
- The client package is a separate component for outbound HTTP calls.

##### Essential details
- Separate static file serving from controller pipeline.
- Dual nature: an ASGI “server” component and a client library component.
- DI container feeding handler parameters and model binding (JSON, query, path).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Network Boundary
    ASGI_SERVER["ASGI Server<br/>(uvicorn/hypercorn)"]:::network

    %% Core Framework
    ASGI_ADAPTER["ASGI Adapter"]:::core
    subgraph "Middleware Pipeline"
        CORE_LOADER["Core Middleware Loader"]:::core
        CORS["CORS"]:::core
        CSRF["CSRF"]:::core
        COMPRESSION["Compression"]:::core
        DATAPROTECTION["Data Protection"]:::core
        DIAGNOSTICS["Diagnostics"]:::core
    end
    Router["Router / Route Table"]:::core
    CONTROLLER_DISPATCHER["Controller Dispatcher"]:::core
    DI_CONTAINER["Dependency Injection Container"]:::core
    BINDINGS["Parameter Bindings"]:::core
    subgraph "Response Builders"
        GENERIC_RESPONSES["Generic Responses"]:::core
        ERROR_UI_TEMPLATES["Error & UI Templates"]:::core
    end

    %% Extension Modules
    subgraph "Static File Module"
        STATIC_HANDLER["Static Files Handler"]:::extension
        DYNAMIC_HANDLER["Dynamic Files Handler"]:::extension
    end
    subgraph "OpenAPI Generator & UI"
        OAPI_V3["OpenAPI v3 Generator"]:::extension
        OAPI_UI["OpenAPI UI Endpoints"]:::extension
        OAPI_COMMON["OpenAPI Common & Docstrings"]:::extension
    end
    subgraph "Auth & Authorization"
        COOKIE_AUTH["Cookie Authentication"]:::extension
        JWT_AUTH["JWT Authentication"]:::extension
        OIDC_AUTH["OIDC Authentication"]:::extension
        AUTHZ_POLICIES["Authorization Policies"]:::extension
    end
    subgraph "Session & Cookie Management"
        SERVER_SESSIONS["Server-side Sessions"]:::extension
        CLIENT_COOKIES["Client-side Cookies"]:::extension
    end
    TEMPLATING["Jinja2 Adapter"]:::extension

    %% Client Library
    subgraph "HTTP Client Library"
        CLIENT_SESSION["Client Session"]:::client
        CONNECTION_POOL["Connection Pool"]:::client
        CLIENT_EXCEPTIONS["Exceptions"]:::client
        CLIENT_COOKIES2["Cookies"]:::client
        CLIENT_API["Main Client API"]:::client
    end

    %% Performance Core
    subgraph "Performance Core"
        URL_P["URL Parsing"]:::perf
        HEADERS_P["Headers"]:::perf
        MESSAGES_P["Messages"]:::perf
        COOKIES_P["Cookies"]:::perf
        CONTENTS_P["Contents Processing"]:::perf
        SCRIBE_P["Scribe / Logging"]:::perf
    end

    %% Common Utilities
    subgraph "Common Utilities"
        ASYNC_FS["Async File Utilities"]:::common
        TYPES["Shared Types"]:::common
        HELPERS["General Helpers"]:::common
    end

    %% Settings & DI
    subgraph "Settings & DI"
        JSON_SETTINGS["JSON Settings"]:::common
        HTML_SETTINGS["HTML Settings"]:::common
        SETTINGS_DI["Settings DI"]:::common
    end

    %% Testing Support
    subgraph "Testing Support"
        TESTCLIENT["TestClient & Simulators"]:::testing
    end

    %% Flow
    ASGI_SERVER --> ASGI_ADAPTER --> CORE_LOADER --> CORS --> CSRF --> COMPRESSION --> DATAPROTECTION --> DIAGNOSTICS --> Router
    Router --> CONTROLLER_DISPATCHER
    DI_CONTAINER --> CONTROLLER_DISPATCHER
    BINDINGS --> CONTROLLER_DISPATCHER
    CONTROLLER_DISPATCHER --> GENERIC_RESPONSES --> ASGI_ADAPTER
    GENERIC_RESPONSES --> ERROR_UI_TEMPLATES --> ASGI_ADAPTER

    %% Static and OpenAPI bypass
    ASGI_ADAPTER --> STATIC_HANDLER --> ASGI_ADAPTER
    ASGI_ADAPTER --> DYNAMIC_HANDLER --> ASGI_ADAPTER
    ASGI_ADAPTER --> OAPI_V3 --> OAPI_UI --> ASGI_ADAPTER
    OAPI_V3 --> OAPI_COMMON

    %% Auth and Sessions in pipeline
    CORE_LOADER --> COOKIE_AUTH --> CORE_LOADER
    CORE_LOADER --> JWT_AUTH --> CORE_LOADER
    CORE_LOADER --> OIDC_AUTH --> CORE_LOADER
    COOKIE_AUTH --> AUTHZ_POLICIES --> CORE_LOADER
    CORE_LOADER --> SERVER_SESSIONS
    CORE_LOADER --> CLIENT_COOKIES

    %% Templating usage
    CONTROLLER_DISPATCHER --> TEMPLATING --> GENERIC_RESPONSES

    %% Client library side
    CLIENT_API --> CLIENT_SESSION --> CONNECTION_POOL
    CLIENT_SESSION --> CLIENT_EXCEPTIONS
    CLIENT_SESSION --> CLIENT_COOKIES2

    %% Performance core integration
    ASGI_ADAPTER -.-> URL_P
    ASGI_ADAPTER -.-> HEADERS_P
    ASGI_ADAPTER -.-> MESSAGES_P
    CLIENT_SESSION -.-> COOKIES_P
    GENERIC_RESPONSES -.-> CONTENTS_P
    CORE_LOADER -.-> SCRIBE_P

    %% Common & Settings
    DI_CONTAINER --> JSON_SETTINGS
    DI_CONTAINER --> HTML_SETTINGS
    DI_CONTAINER --> SETTINGS_DI
    ASGI_ADAPTER --> ASYNC_FS
    CONTROLLER_DISPATCHER --> TYPES
    CORE_LOADER --> HELPERS

    %% Testing
    TESTCLIENT --> ASGI_ADAPTER

    %% Click Events
    click ASGI_ADAPTER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/asgi.py"
    click CORE_LOADER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/middlewares.py"
    click CORS "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/cors.py"
    click CSRF "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/csrf.py"
    click COMPRESSION "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/compression.py"
    click DATAPROTECTION "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/dataprotection.py"
    click DIAGNOSTICS "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/diagnostics.py"
    click Router "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/routing.py"
    click CONTROLLER_DISPATCHER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/controllers.py"
    click DI_CONTAINER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/di.py"
    click BINDINGS "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/bindings.py"
    click GENERIC_RESPONSES "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/responses.py"
    click ERROR_UI_TEMPLATES "https://github.com/neoteroi/blacksheep/tree/main/blacksheep/server/res/"
    click STATIC_HANDLER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/files/static.py"
    click DYNAMIC_HANDLER "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/files/dynamic.py"
    click OAPI_V3 "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/openapi/v3.py"
    click OAPI_UI "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/openapi/ui.py"
    click OAPI_COMMON "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/openapi/common.py"
    click COOKIE_AUTH "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/authentication/cookie.py"
    click JWT_AUTH "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/authentication/jwt.py"
    click OIDC_AUTH "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/authentication/oidc.py"
    click AUTHZ_POLICIES "https://github.com/neoteroi/blacksheep/tree/main/blacksheep/server/authorization/"
    click SERVER_SESSIONS "https://github.com/neoteroi/blacksheep/tree/main/blacksheep/sessions/"
    click CLIENT_COOKIES "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/cookies.py"
    click TEMPLATING "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/server/rendering/jinja2.py"
    click CLIENT_SESSION "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/session.py"
    click CONNECTION_POOL "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/pool.py"
    click CLIENT_EXCEPTIONS "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/exceptions.py"
    click CLIENT_COOKIES2 "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/cookies.py"
    click CLIENT_API "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/client/connection.py"
    click URL_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/url.pyx"
    click HEADERS_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/headers.pyx"
    click MESSAGES_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/messages.pyx"
    click COOKIES_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/cookies.pyx"
    click CONTENTS_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/contents.pyx"
    click SCRIBE_P "https://github.com/neoteroi/blacksheep/blob/main/blacksheep/scribe.pyx"

    %% Styles
    classDef network fill:#BEE3F8,stroke:#3182CE,color:#1A365D,stroke-width:2px;
    classDef core fill:#C6F6D5,stroke:#2F855A,color:#22543D,stroke-width:2px;
    classDef extension fill:#FEEBC8,stroke:#DD6B20,color:#652B19,stroke-width:2px;
    classDef client fill:#E2E8F0,stroke:#4A5568,color:#1A202C,stroke-width:2px;
    classDef perf fill:#F5E1FD,stroke:#9F7AEA,color:#44337A,stroke-width:2px;
    classDef common fill:#FFF5F7,stroke:#D53F8C,color:#702459,stroke-width:2px;
    classDef testing fill:#FEFCBF,stroke:#D69E2E,color:#744210,stroke-width:2px;
```
