# falconry/falcon architecture

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

- Interactive diagram: https://gitdiagram.com/falconry/falcon
- Repository: https://github.com/falconry/falcon

## Overview

##### Project type and purpose
- This is an open-source, minimalist ASGI/WSGI web framework (Falcon) for building REST APIs and microservices.
- It provides a bare-metal HTTP pipeline with pluggable middleware, hooks, routers, resource handlers, media handlers, error handlers, and “sinks” (custom request dispatchers).

##### File structure
- Top-level “falcon/” directory contains the source modules:
- asgi/ (ASGI adapter)
- app.py (App class)
- routing/ (router, converters, static routing)
- media/ (parsers, renderers, validators)
- middleware.py, hooks.py
- request.py, response.py
- errors.py, http_error.py, redirects.py
- cyutil/ (Cython‐optimised utilities)
- testing/ (client mocks, helpers)
- cmd/ (CLI tools: bench, inspect_app)
- Examples, docs, tests, bench, docker, tools folders surround the core library, but the heart of the architecture lives in “falcon/”.

##### README for insights
- The README emphasizes a central App instance callable by any WSGI or ASGI server.
- Requests flow through middleware → hooks → routing → responder/resource → response.
- Extensibility via middleware, hooks, custom error handlers, and sinks.

##### Main components
a. External HTTP servers
- WSGI Server (Gunicorn, uWSGI, wsgiref)
- ASGI Server (Uvicorn, Hypercorn)
b. Falcon Adapters
- falcon.App (WSGI)
- falcon.asgi.App (ASGI)
c. Core Pipeline
1. Request Factory
– Builds Request object (falcon.request.Request or falcon.asgi.request.Request)
2. Middleware Chain
– process_request(req, resp)
3. Pre-routing Hooks
– before/after hooks on resources
4. Router
– Selects resource based on URL pattern (falcon.routing)
5. Resource Handler
– on_get, on_post, etc. methods on user classes
6. Error Handlers
– Custom handlers for exceptions
7. Sink Dispatchers
– Catch-all or regex dispatch
8. Media Handlers
– req.media, resp.media using falcon.media.*
9. Post-processing Hooks
– process_response in middleware
10. Response Finalizer
– Serializes Response object (falcon.response.Response) back to HTTP
d. Supporting modules
- Cython utilities (falcon.cyutil) for performance
- Utilities (falcon.util)
- CLI tools (falcon.cmd)
- Testing harness (falcon.testing)
e. Extension points
- Middleware classes
- Hooks decorators
- Custom error handlers (app.add_error_handler)
- Custom sinks (app.add_sink)

##### Relationships and data flow
- HTTP Client → HTTP Server → Falcon Adapter → Pipeline stages (middleware → hooks → routing → resource/sink → media serialization → error handlers) → Falcon Adapter → HTTP Server → HTTP Client
- The adapter wraps the entire pipeline, converting between HTTP-level events and Falcon’s Request/Response objects.

##### Architectural patterns and design principles
- Chain of Responsibility (middleware, hooks)
- Plugin architecture (error handlers, sinks)
- Separation of concerns (adapters vs. routing vs. media vs. business logic)
- Minimal abstractions: Straight mapping of HTTP verbs to resource methods
- Optional Cython compilation for hot code paths

##### Detail-level advice
- Do not omit any pipeline stage—Falcon’s value comes from the lightweight, well-defined flow.
- Middleware/hook ordering explicitly.
- If desired, include a zoomed-in view of “Router” showing static vs. compiled vs. converters.
- Optionally, overlay throughput optimization notes (e.g., “Cython hot paths” in falcon.cyutil).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External systems
    HTTPClient["HTTP Client"]:::external
    WSGIServer["WSGI Server"]:::external
    ASGIServer["ASGI Server"]:::external

    HTTPClient --> WSGIServer
    HTTPClient --> ASGIServer

    WSGIServer --> WSGIAdapter
    ASGIServer --> ASGIAdapter

    %% Falcon Adapters
    subgraph "Falcon Adapters"
        direction TB
        WSGIAdapter["falcon.App<br/>(WSGI Adapter)"]:::core
        ASGIAdapter["falcon.asgi.App<br/>(ASGI Adapter)"]:::core
    end

    WSGIAdapter --> RFWSGI
    ASGIAdapter --> RFASGI

    %% Pipeline stages
    RFWSGI["Request Factory<br/>(WSGI)"]:::core
    RFASGI["Request Factory<br/>(ASGI)"]:::core
    Middleware["Middleware Chain"]:::extension
    Hooks["Hooks<br/>(before/after)"]:::extension
    Router["Router<br/>(falcon.routing)"]:::core
    ResourceHandler["Resource Handler<br/>(on_get/on_post)"]:::core
    ErrorHandlers["Error Handlers"]:::extension
    SinkDispatchers["Sink Dispatchers"]:::extension
    MediaHandlers["Media Handlers"]:::core
    ResponseFinalizer["Response Finalizer"]:::core

    %% Pipeline flow
    RFWSGI --> Middleware
    RFASGI --> Middleware
    Middleware --> Hooks
    Hooks --> Router
    Router --> ResourceHandler
    ResourceHandler --> MediaHandlers
    MediaHandlers --> ResponseFinalizer
    ResponseFinalizer --> WSGIAdapter
    ResponseFinalizer --> ASGIAdapter

    %% Support modules (inside core boundary)
    subgraph "Core Library"
        direction TB
        CythonUtils["Cython Utilities"]:::support
        Utilities["General Utilities"]:::support
        CLI["CLI Tools"]:::support
        Testing["Testing Harness"]:::support
    end

    %% Relationships to support modules
    Router --> CythonUtils
    ResourceHandler --> Utilities
    WSGIAdapter --> CLI
    WSGIAdapter --> Testing

    %% Click events
    click WSGIAdapter "https://github.com/falconry/falcon/blob/master/falcon/app.py"
    click ASGIAdapter "https://github.com/falconry/falcon/blob/master/falcon/asgi/app.py"
    click RFWSGI "https://github.com/falconry/falcon/blob/master/falcon/request.py"
    click RFASGI "https://github.com/falconry/falcon/blob/master/falcon/asgi/request.py"
    click Middleware "https://github.com/falconry/falcon/blob/master/falcon/middleware.py"
    click Hooks "https://github.com/falconry/falcon/blob/master/falcon/hooks.py"
    click Router "https://github.com/falconry/falcon/blob/master/falcon/routing/__init__.py"
    click ResourceHandler "https://github.com/falconry/falcon/blob/master/falcon/responders.py"
    click ErrorHandlers "https://github.com/falconry/falcon/blob/master/falcon/errors.py"
    click SinkDispatchers "https://github.com/falconry/falcon/blob/master/falcon/app_helpers.py"
    click CythonUtils "https://github.com/falconry/falcon/blob/master/falcon/cyutil/__init__.py"
    click Utilities "https://github.com/falconry/falcon/blob/master/falcon/util/__init__.py"
    click CLI "https://github.com/falconry/falcon/blob/master/falcon/cmd/bench.py"
    click Testing "https://github.com/falconry/falcon/blob/master/falcon/testing/client.py"

    %% Styles
    classDef external fill:#f9c784,stroke:#333,stroke-width:1px
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef extension fill:#98fb98,stroke:#333,stroke-width:1px
    classDef support fill:#e0e0e0,stroke:#333,stroke-width:1px
```
