# eukalpia/podbus architecture

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

- Interactive diagram: https://gitdiagram.com/eukalpia/podbus
- Repository: https://github.com/eukalpia/podbus

## Overview

PodBus is a Dart messaging toolkit, not a broker. An application uses shared contracts to publish or consume typed messages, or enqueue durable jobs; a selected transport provides broker delivery, while policy and PostgreSQL helpers support retries, idempotency, and database-publish reliability. The README also describes observability and Serverpod integration. Connections below follow documented package capabilities and examples; individual implementation call paths were not sampled.

Main entry points: [`packages/podbus_core/lib/src/message_bus.dart`](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/message_bus.dart) (Messaging contracts), [`packages/podbus_core/lib/src/durable_job_queue.dart`](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/durable_job_queue.dart) (Durable job contract), [`packages/podbus_nats/lib/src/nats_message_bus.dart`](https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_message_bus.dart) (NATS Core bus), [`packages/podbus_nats/lib/src/nats_jetstream_job_queue.dart`](https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_jetstream_job_queue.dart) (JetStream jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core contracts"]
  node_contracts["Messaging contracts<br/>[message_bus.dart]"]
  node_codec["Typed JSON codec<br/>[codec.dart]"]
  node_capabilities["Capability checks<br/>[capabilities.dart]"]
  node_policies["Retry policies<br/>[policies.dart]"]
  node_job_contract["Durable job contract"]
end

subgraph group_transports["Transport adapters"]
  node_nats_bus["NATS Core bus"]
  node_nats_jobs["JetStream jobs"]
  node_rabbit["RabbitMQ adapter"]
  node_kafka["Kafka adapter"]
end

subgraph group_reliability["Reliability state"]
  node_outbox[("Transactional outbox")]
  node_inbox[("Inbox leases")]
  node_idempotency[("Persistent idempotency")]
end

subgraph group_integrations["Operations integrations"]
  node_observability["Metrics and tracing"]
  node_health["Health probes<br/>[health_probe.dart]"]
  node_serverpod["Serverpod lifecycle"]
end

node_app(("Dart application"))
node_broker{{"Message brokers"}}

node_app -->|"uses API"| node_contracts
node_app -->|"checks support"| node_capabilities
node_contracts -->|"encodes payloads"| node_codec
node_contracts -->|"selects transport"| node_nats_bus
node_contracts -->|"selects transport"| node_rabbit
node_contracts -->|"selects transport"| node_kafka
node_app -->|"enqueues jobs"| node_job_contract
node_job_contract -->|"implemented by"| node_nats_jobs
node_nats_bus -->|"publishes messages"| node_broker
node_nats_jobs -->|"runs durable workers"| node_broker
node_rabbit -->|"publishes messages"| node_broker
node_kafka -->|"publishes messages"| node_broker
node_app -->|"configures retries"| node_policies
node_app -->|"uses for atomic publish"| node_outbox
node_app -->|"uses for deduplication"| node_inbox
node_app -->|"uses persistent keys"| node_idempotency
node_app -->|"configures hooks"| node_observability
node_app -->|"uses probes"| node_health
node_app -->|"integrates lifecycle"| node_serverpod

click node_contracts "https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/message_bus.dart"
click node_codec "https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/codec.dart"
click node_capabilities "https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/capabilities.dart"
click node_policies "https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/policies.dart"
click node_job_contract "https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/durable_job_queue.dart"
click node_nats_bus "https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_message_bus.dart"
click node_nats_jobs "https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_jetstream_job_queue.dart"
click node_rabbit "https://github.com/eukalpia/podbus/blob/main/packages/podbus_rabbitmq/lib/src/rabbitmq_message_bus.dart"
click node_kafka "https://github.com/eukalpia/podbus/blob/main/packages/podbus_kafka/lib/src/kafka_event_bus.dart"
click node_outbox "https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_outbox.dart"
click node_inbox "https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_inbox.dart"
click node_idempotency "https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_idempotency_store.dart"
click node_observability "https://github.com/eukalpia/podbus/blob/main/packages/podbus_observability/lib/src/instrumentation.dart"
click node_health "https://github.com/eukalpia/podbus/blob/main/packages/podbus_observability/lib/src/health_probe.dart"
click node_serverpod "https://github.com/eukalpia/podbus/blob/main/packages/podbus_serverpod/lib/src/serverpod_messaging.dart"

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_contracts,node_codec,node_capabilities,node_policies,node_job_contract toneBlue
class node_nats_bus,node_nats_jobs,node_rabbit,node_kafka toneAmber
class node_outbox,node_inbox,node_idempotency toneMint
class node_observability,node_health,node_serverpod toneRose
class node_app,node_broker toneIndigo
```

## Components

### Core contracts

- [Messaging contracts](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/message_bus.dart): `packages/podbus_core/lib/src/message_bus.dart`
- [Typed JSON codec](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/codec.dart): `packages/podbus_core/lib/src/codec.dart`
- [Capability checks](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/capabilities.dart): `packages/podbus_core/lib/src/capabilities.dart`
- [Retry policies](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/policies.dart): `packages/podbus_core/lib/src/policies.dart`
- [Durable job contract](https://github.com/eukalpia/podbus/blob/main/packages/podbus_core/lib/src/durable_job_queue.dart): `packages/podbus_core/lib/src/durable_job_queue.dart`

### Transport adapters

- [NATS Core bus](https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_message_bus.dart): `packages/podbus_nats/lib/src/nats_message_bus.dart`
- [JetStream jobs](https://github.com/eukalpia/podbus/blob/main/packages/podbus_nats/lib/src/nats_jetstream_job_queue.dart): `packages/podbus_nats/lib/src/nats_jetstream_job_queue.dart`
- [RabbitMQ adapter](https://github.com/eukalpia/podbus/blob/main/packages/podbus_rabbitmq/lib/src/rabbitmq_message_bus.dart): `packages/podbus_rabbitmq/lib/src/rabbitmq_message_bus.dart`
- [Kafka adapter](https://github.com/eukalpia/podbus/blob/main/packages/podbus_kafka/lib/src/kafka_event_bus.dart): `packages/podbus_kafka/lib/src/kafka_event_bus.dart`

### Reliability state

- [Transactional outbox](https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_outbox.dart): `packages/podbus_postgres/lib/src/postgres_outbox.dart`
- [Inbox leases](https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_inbox.dart): `packages/podbus_postgres/lib/src/postgres_inbox.dart`
- [Persistent idempotency](https://github.com/eukalpia/podbus/blob/main/packages/podbus_postgres/lib/src/postgres_idempotency_store.dart): `packages/podbus_postgres/lib/src/postgres_idempotency_store.dart`

### Operations integrations

- [Metrics and tracing](https://github.com/eukalpia/podbus/blob/main/packages/podbus_observability/lib/src/instrumentation.dart): `packages/podbus_observability/lib/src/instrumentation.dart`
- [Health probes](https://github.com/eukalpia/podbus/blob/main/packages/podbus_observability/lib/src/health_probe.dart): `packages/podbus_observability/lib/src/health_probe.dart`
- [Serverpod lifecycle](https://github.com/eukalpia/podbus/blob/main/packages/podbus_serverpod/lib/src/serverpod_messaging.dart): `packages/podbus_serverpod/lib/src/serverpod_messaging.dart`

### Other components

- **Dart application**
- **Message brokers**

## Connections

- Dart application → Messaging contracts: uses API (evidence: `README.md`)
- Dart application → Capability checks: checks support (evidence: `README.md`)
- Messaging contracts → Typed JSON codec: encodes payloads (evidence: `README.md`)
- Messaging contracts → NATS Core bus: selects transport (evidence: `README.md`)
- Messaging contracts → RabbitMQ adapter: selects transport (evidence: `README.md`)
- Messaging contracts → Kafka adapter: selects transport (evidence: `README.md`)
- Dart application → Durable job contract: enqueues jobs (evidence: `README.md`)
- Durable job contract → JetStream jobs: implemented by (evidence: `README.md`)
- NATS Core bus → Message brokers: publishes messages (evidence: `README.md`)
- JetStream jobs → Message brokers: runs durable workers (evidence: `README.md`)
- RabbitMQ adapter → Message brokers: publishes messages (evidence: `README.md`)
- Kafka adapter → Message brokers: publishes messages (evidence: `README.md`)
- Dart application → Retry policies: configures retries (evidence: `README.md`)
- Dart application → Transactional outbox: uses for atomic publish (evidence: `README.md`)
- Dart application → Inbox leases: uses for deduplication (evidence: `README.md`)
- Dart application → Persistent idempotency: uses persistent keys (evidence: `README.md`)
- Dart application → Metrics and tracing: configures hooks (evidence: `README.md`)
- Dart application → Health probes: uses probes (evidence: `README.md`)
- Dart application → Serverpod lifecycle: integrates lifecycle (evidence: `README.md`)
