# dj-bolt/django-bolt architecture

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

- Interactive diagram: https://gitdiagram.com/dj-bolt/django-bolt
- Repository: https://github.com/dj-bolt/django-bolt

## Overview

Django-Bolt is a typed Django API framework whose Rust/Actix server handles HTTP routing and request processing, then bridges requests to Python endpoint handlers. The main workflow runs from a client request through route dispatch, typed argument extraction and validation, the Python handler, and response serialization. It also supports Django middleware and admin mounts, OpenAPI, WebSockets, streaming, and MCP. The README documents these capabilities; sampled source confirms selected runtime and integration links, so unsampled wiring is omitted.

Main entry points: [`python/django_bolt/api.py`](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/api.py) (BoltAPI), [`src/handler.rs`](https://github.com/dj-bolt/django-bolt/blob/master/src/handler.rs) (Request Handler), [`src/server.rs`](https://github.com/dj-bolt/django-bolt/blob/master/src/server.rs) (Actix Server), [`crates/bolt-mcp/src/handler.rs`](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-mcp/src/handler.rs) (MCP Protocol Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Definition"]
  node_api["BoltAPI<br/>[api.py]"]
  node_routes["Route Registry<br/>[router.py]"]
  node_args["Argument Extraction<br/>[runtime.py]"]
  node_serializers["Serializers<br/>[base.py]"]
end

subgraph group_runtime["HTTP Runtime"]
  node_server["Actix Server<br/>[server.rs]"]
  node_handler["Request Handler<br/>[handler.rs]"]
  node_pipeline["Request Validation"]
  node_response["Response Encoding<br/>[response_body.rs]"]
  node_middleware["Middleware<br/>[middleware.py]"]
  node_errors["Error Handling<br/>[error_handlers.py]"]
end

subgraph group_channels["Protocols and Docs"]
  node_admin["Django Admin Mount<br/>[routes.py]"]
  node_openapi["OpenAPI Docs<br/>[routes.py]"]
  node_websocket["WebSockets<br/>[handler.rs]"]
  node_streaming["Streaming Responses<br/>[streaming.rs]"]
end

subgraph group_mcp["MCP Integration"]
  node_mcp_api["MCP Registration<br/>[server.py]"]
  node_mcp_handler["MCP Protocol Handler<br/>[handler.rs]"]
  node_mcp_registry["MCP Registry<br/>[registry.rs]"]
  node_python_dispatch["MCP Python Dispatch<br/>[_dispatch.py]"]
end

node_client(("API Client"))
node_mcp_client(("MCP Client"))

node_client -->|"sends request"| node_server
node_server -->|"dispatches HTTP"| node_handler
node_handler -->|"validates inputs"| node_pipeline
node_pipeline -->|"extracts arguments"| node_args
node_handler -->|"invokes handler"| node_api
node_api -->|"registers routes"| node_routes
node_api -->|"uses serializers"| node_serializers
node_handler -->|"encodes response"| node_response
node_handler -->|"applies middleware"| node_middleware
node_handler -->|"formats exceptions"| node_errors
node_api -->|"mounts admin"| node_admin
node_api -->|"registers docs"| node_openapi
node_server -->|"dispatches upgrades"| node_websocket
node_api -->|"returns streams"| node_streaming
node_mcp_client -->|"sends protocol requests"| node_mcp_handler
node_api -->|"mounts MCP"| node_mcp_api
node_mcp_api -->|"compiles registrations"| node_mcp_registry
node_mcp_handler -->|"reads catalog"| node_mcp_registry
node_mcp_handler -->|"dispatches execution"| node_python_dispatch

click node_api "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/api.py"
click node_routes "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/router.py"
click node_args "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/_kwargs/runtime.py"
click node_serializers "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/serializers/base.py"
click node_server "https://github.com/dj-bolt/django-bolt/blob/master/src/server.rs"
click node_handler "https://github.com/dj-bolt/django-bolt/blob/master/src/handler.rs"
click node_pipeline "https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-core/src/request_pipeline.rs"
click node_response "https://github.com/dj-bolt/django-bolt/blob/master/src/response_body.rs"
click node_middleware "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/middleware/middleware.py"
click node_errors "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/error_handlers.py"
click node_admin "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/admin/routes.py"
click node_openapi "https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/openapi/routes.py"
click node_websocket "https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-websocket/src/handler.rs"
click node_streaming "https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-core/src/streaming.rs"
click node_mcp_api "https://github.com/dj-bolt/django-bolt/blob/master/python/bolt-mcp/src/bolt_mcp/server.py"
click node_mcp_handler "https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-mcp/src/handler.rs"
click node_mcp_registry "https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-mcp/src/registry.rs"
click node_python_dispatch "https://github.com/dj-bolt/django-bolt/blob/master/python/bolt-mcp/src/bolt_mcp/_dispatch.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_api,node_routes,node_args,node_serializers,node_client,node_mcp_client toneBlue
class node_server,node_handler,node_pipeline,node_response,node_middleware,node_errors toneAmber
class node_admin,node_openapi,node_websocket,node_streaming toneMint
class node_mcp_api,node_mcp_handler,node_mcp_registry,node_python_dispatch toneRose
```

## Components

### API Definition

- [BoltAPI](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/api.py): `python/django_bolt/api.py`
- [Route Registry](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/router.py): `python/django_bolt/router.py`
- [Argument Extraction](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/_kwargs/runtime.py): `python/django_bolt/_kwargs/runtime.py`
- [Serializers](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/serializers/base.py): `python/django_bolt/serializers/base.py`

### HTTP Runtime

- [Actix Server](https://github.com/dj-bolt/django-bolt/blob/master/src/server.rs): `src/server.rs`
- [Request Handler](https://github.com/dj-bolt/django-bolt/blob/master/src/handler.rs): `src/handler.rs`
- [Request Validation](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-core/src/request_pipeline.rs): `crates/bolt-core/src/request_pipeline.rs`
- [Response Encoding](https://github.com/dj-bolt/django-bolt/blob/master/src/response_body.rs): `src/response_body.rs`
- [Middleware](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/middleware/middleware.py): `python/django_bolt/middleware/middleware.py`
- [Error Handling](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/error_handlers.py): `python/django_bolt/error_handlers.py`

### Protocols and Docs

- [Django Admin Mount](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/admin/routes.py): `python/django_bolt/admin/routes.py`
- [OpenAPI Docs](https://github.com/dj-bolt/django-bolt/blob/master/python/django_bolt/openapi/routes.py): `python/django_bolt/openapi/routes.py`
- [WebSockets](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-websocket/src/handler.rs): `crates/bolt-websocket/src/handler.rs`
- [Streaming Responses](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-core/src/streaming.rs): `crates/bolt-core/src/streaming.rs`

### MCP Integration

- [MCP Registration](https://github.com/dj-bolt/django-bolt/blob/master/python/bolt-mcp/src/bolt_mcp/server.py): `python/bolt-mcp/src/bolt_mcp/server.py`
- [MCP Protocol Handler](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-mcp/src/handler.rs): `crates/bolt-mcp/src/handler.rs`
- [MCP Registry](https://github.com/dj-bolt/django-bolt/blob/master/crates/bolt-mcp/src/registry.rs): `crates/bolt-mcp/src/registry.rs`
- [MCP Python Dispatch](https://github.com/dj-bolt/django-bolt/blob/master/python/bolt-mcp/src/bolt_mcp/_dispatch.py): `python/bolt-mcp/src/bolt_mcp/_dispatch.py`

### Other components

- **API Client**
- **MCP Client**

## Connections

- API Client → Actix Server: sends request
- Actix Server → Request Handler: dispatches HTTP
- Request Handler → Request Validation: validates inputs
- Request Validation → Argument Extraction: extracts arguments
- Request Handler → BoltAPI: invokes handler
- BoltAPI → Route Registry: registers routes
- BoltAPI → Serializers: uses serializers
- Request Handler → Response Encoding: encodes response
- Request Handler → Middleware: applies middleware
- Request Handler → Error Handling: formats exceptions
- BoltAPI → Django Admin Mount: mounts admin
- BoltAPI → OpenAPI Docs: registers docs
- Actix Server → WebSockets: dispatches upgrades
- BoltAPI → Streaming Responses: returns streams
- MCP Client → MCP Protocol Handler: sends protocol requests
- BoltAPI → MCP Registration: mounts MCP
- MCP Registration → MCP Registry: compiles registrations
- MCP Protocol Handler → MCP Registry: reads catalog
- MCP Protocol Handler → MCP Python Dispatch: dispatches execution