# ag2ai/faststream architecture

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

- Interactive diagram: https://gitdiagram.com/ag2ai/faststream
- Repository: https://github.com/ag2ai/faststream

## Overview

FastStream is an asynchronous Python framework for building event-driven services on Kafka, RabbitMQ, NATS, Redis, and MQTT. In the principal workflow, an application registers broker handlers, starts its broker connections, receives and parses messages, and invokes application handlers; publishers send messages back through broker-specific clients. The repository also provides lifecycle management, serialization, dependency injection, AsyncAPI documentation, in-memory testing, observability, and ASGI/FastAPI integration. The graph uses documented capabilities and sampled call evidence; several feature links are dashed because their implementation was not sampled.

Main entry points: [`faststream/_internal/application.py`](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/application.py) (Application), [`faststream/_internal/endpoint/subscriber/usecase.py`](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/endpoint/subscriber/usecase.py) (Subscriber runtime), [`faststream/_internal/broker/router.py`](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/broker/router.py) (Broker router), [`faststream/_internal/middlewares.py`](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/middlewares.py) (Middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application lifecycle"]
  node_application["Application<br/>[application.py]"]
  node_asgi["ASGI application<br/>[app.py]"]
end

subgraph group_messaging["Messaging runtime"]
  node_broker_router["Broker router<br/>[router.py]"]
  node_subscriber["Subscriber runtime<br/>[usecase.py]"]
  node_message_parser["Message parsing<br/>[parser.py]"]
  node_message_types["Message model<br/>[message.py]"]
  node_publisher["Publisher runtime<br/>[usecase.py]"]
  node_middleware["Middleware<br/>[middlewares.py]"]
  node_context["Context repository<br/>[repository.py]"]
end

subgraph group_integrations["Broker integrations"]
  node_kafka["Kafka adapter<br/>[registrator.py]"]
  node_rabbit["RabbitMQ adapter<br/>[registrator.py]"]
  node_nats["NATS adapter<br/>[registrator.py]"]
  node_redis["Redis adapter<br/>[registrator.py]"]
  node_confluent["Confluent adapter<br/>[registrator.py]"]
  node_mqtt["MQTT adapter<br/>[registrator.py]"]
end

subgraph group_capabilities["Framework capabilities"]
  node_asyncapi["AsyncAPI generation<br/>[factory.py]"]
  node_testing["In-memory testing<br/>[broker.py]"]
  node_observability["Metrics and tracing<br/>[middleware.py]"]
  node_fastapi["FastAPI integration<br/>[router.py]"]
end

node_developer(("Service developer"))
node_broker_service{{"Message broker"}}

node_developer -->|"configures"| node_application
node_application -.->|"registers handlers"| node_broker_router
node_application -->|"starts connections"| node_broker_service
node_broker_router -->|"registers subscriber"| node_subscriber
node_broker_router -->|"registers publisher"| node_publisher
node_subscriber -.->|"parses messages"| node_message_parser
node_subscriber -.->|"handles messages"| node_message_types
node_publisher -.->|"publishes messages"| node_broker_service
node_middleware -.->|"wraps processing"| node_subscriber
node_application -.->|"shares context"| node_context
node_kafka -.->|"connects to"| node_broker_service
node_rabbit -.->|"connects to"| node_broker_service
node_nats -.->|"connects to"| node_broker_service
node_redis -.->|"connects to"| node_broker_service
node_confluent -.->|"connects to"| node_broker_service
node_mqtt -.->|"connects to"| node_broker_service
node_application -.->|"generates contract"| node_asyncapi
node_developer -.->|"tests handlers"| node_testing
node_middleware -.->|"supports instrumentation"| node_observability
node_asgi -->|"extends lifecycle"| node_application
node_fastapi -->|"integrates framework"| node_application

click node_application "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/application.py"
click node_asgi "https://github.com/ag2ai/faststream/blob/main/faststream/asgi/app.py"
click node_broker_router "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/broker/router.py"
click node_subscriber "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/endpoint/subscriber/usecase.py"
click node_message_parser "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/parser.py"
click node_message_types "https://github.com/ag2ai/faststream/blob/main/faststream/message/message.py"
click node_publisher "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/endpoint/publisher/usecase.py"
click node_middleware "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/middlewares.py"
click node_context "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/context/repository.py"
click node_kafka "https://github.com/ag2ai/faststream/blob/main/faststream/kafka/broker/registrator.py"
click node_rabbit "https://github.com/ag2ai/faststream/blob/main/faststream/rabbit/broker/registrator.py"
click node_nats "https://github.com/ag2ai/faststream/blob/main/faststream/nats/broker/registrator.py"
click node_redis "https://github.com/ag2ai/faststream/blob/main/faststream/redis/broker/registrator.py"
click node_confluent "https://github.com/ag2ai/faststream/blob/main/faststream/confluent/broker/registrator.py"
click node_mqtt "https://github.com/ag2ai/faststream/blob/main/faststream/mqtt/broker/registrator.py"
click node_asyncapi "https://github.com/ag2ai/faststream/blob/main/faststream/specification/asyncapi/factory.py"
click node_testing "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/testing/broker.py"
click node_observability "https://github.com/ag2ai/faststream/blob/main/faststream/prometheus/middleware.py"
click node_fastapi "https://github.com/ag2ai/faststream/blob/main/faststream/_internal/fastapi/router.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_application,node_asgi toneBlue
class node_broker_router,node_subscriber,node_message_parser,node_message_types,node_publisher,node_middleware,node_context toneAmber
class node_kafka,node_rabbit,node_nats,node_redis,node_confluent,node_mqtt toneMint
class node_asyncapi,node_testing,node_observability,node_fastapi toneRose
class node_developer,node_broker_service toneIndigo
```

## Components

### Application lifecycle

- [Application](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/application.py): `faststream/_internal/application.py`
- [ASGI application](https://github.com/ag2ai/faststream/blob/main/faststream/asgi/app.py): `faststream/asgi/app.py`

### Messaging runtime

- [Broker router](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/broker/router.py): `faststream/_internal/broker/router.py`
- [Subscriber runtime](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/endpoint/subscriber/usecase.py): `faststream/_internal/endpoint/subscriber/usecase.py`
- [Message parsing](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/parser.py): `faststream/_internal/parser.py`
- [Message model](https://github.com/ag2ai/faststream/blob/main/faststream/message/message.py): `faststream/message/message.py`
- [Publisher runtime](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/endpoint/publisher/usecase.py): `faststream/_internal/endpoint/publisher/usecase.py`
- [Middleware](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/middlewares.py): `faststream/_internal/middlewares.py`
- [Context repository](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/context/repository.py): `faststream/_internal/context/repository.py`

### Broker integrations

- [Kafka adapter](https://github.com/ag2ai/faststream/blob/main/faststream/kafka/broker/registrator.py): `faststream/kafka/broker/registrator.py`
- [RabbitMQ adapter](https://github.com/ag2ai/faststream/blob/main/faststream/rabbit/broker/registrator.py): `faststream/rabbit/broker/registrator.py`
- [NATS adapter](https://github.com/ag2ai/faststream/blob/main/faststream/nats/broker/registrator.py): `faststream/nats/broker/registrator.py`
- [Redis adapter](https://github.com/ag2ai/faststream/blob/main/faststream/redis/broker/registrator.py): `faststream/redis/broker/registrator.py`
- [Confluent adapter](https://github.com/ag2ai/faststream/blob/main/faststream/confluent/broker/registrator.py): `faststream/confluent/broker/registrator.py`
- [MQTT adapter](https://github.com/ag2ai/faststream/blob/main/faststream/mqtt/broker/registrator.py): `faststream/mqtt/broker/registrator.py`

### Framework capabilities

- [AsyncAPI generation](https://github.com/ag2ai/faststream/blob/main/faststream/specification/asyncapi/factory.py): `faststream/specification/asyncapi/factory.py`
- [In-memory testing](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/testing/broker.py): `faststream/_internal/testing/broker.py`
- [Metrics and tracing](https://github.com/ag2ai/faststream/blob/main/faststream/prometheus/middleware.py): `faststream/prometheus/middleware.py`
- [FastAPI integration](https://github.com/ag2ai/faststream/blob/main/faststream/_internal/fastapi/router.py): `faststream/_internal/fastapi/router.py`

### Other components

- **Service developer**
- **Message broker**

## Connections

- Service developer → Application: configures
- Application → Broker router: registers handlers
- Application → Message broker: starts connections (evidence: `faststream/_internal/application.py`)
- Broker router → Subscriber runtime: registers subscriber (evidence: `faststream/_internal/broker/router.py`)
- Broker router → Publisher runtime: registers publisher (evidence: `faststream/_internal/broker/router.py`)
- Subscriber runtime → Message parsing: parses messages
- Subscriber runtime → Message model: handles messages
- Publisher runtime → Message broker: publishes messages
- Middleware → Subscriber runtime: wraps processing
- Application → Context repository: shares context
- Kafka adapter → Message broker: connects to
- RabbitMQ adapter → Message broker: connects to
- NATS adapter → Message broker: connects to
- Redis adapter → Message broker: connects to
- Confluent adapter → Message broker: connects to
- MQTT adapter → Message broker: connects to
- Application → AsyncAPI generation: generates contract
- Service developer → In-memory testing: tests handlers
- Middleware → Metrics and tracing: supports instrumentation
- ASGI application → Application: extends lifecycle (evidence: `faststream/asgi/app.py`)
- FastAPI integration → Application: integrates framework (evidence: `faststream/_internal/fastapi/router.py`)
