# namastack/namastack-outbox architecture

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

- Interactive diagram: https://gitdiagram.com/namastack/namastack-outbox
- Repository: https://github.com/namastack/namastack-outbox

## Overview

Namastack Outbox is a Spring Boot transactional outbox: application code schedules an event alongside business data, the runtime persists and asynchronously processes it, then configured handlers or broker integrations deliver it. The core also covers ordered processing, retries, horizontal partitioning, context propagation and runtime status; persistence can use JDBC, JPA or MongoDB. The README documents the product-level workflow and capabilities. Source excerpts are partial, so finer runtime wiring and unsampled integrations are represented only where documented, not inferred as direct calls.

Main entry points: [`namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt`](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt) (Record repository), [`namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt`](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt) (Outbox service), [`namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt`](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt) (Outbox API), [`namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt`](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt) (Handler routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Event API"]
  node_outbox_api["Outbox API<br/>[Outbox.kt]"]
  node_context["Context collection"]
  node_record["Outbox record<br/>[OutboxRecord.kt]"]
  node_routing["Handler routing"]
end

subgraph group_runtime["Processing Runtime"]
  node_scheduler["Polling scheduler"]
  node_service["Outbox service<br/>[OutboxService.kt]"]
  node_processor["Record processing"]
  node_retry["Retry policies"]
  node_partition["Partition coordination"]
end

subgraph group_persistence["Persistence"]
  node_record_repo["Record repository"]
  node_jdbc["JDBC adapter"]
  node_jpa["JPA adapter"]
  node_mongo["Mongo adapter"]
end

subgraph group_delivery["Delivery and Operations"]
  node_broker(("Messaging brokers"))
  node_kafka["Kafka integration"]
  node_rabbit["RabbitMQ integration"]
  node_sns["AWS SNS integration"]
  node_observability["Metrics and tracing"]
  node_actuator["Actuator endpoint"]
end

node_app(("Spring application"))
node_database[("Configured database")]
node_handlers(("Application handlers"))

node_app -->|"schedules event"| node_outbox_api
node_outbox_api -.->|"collects context"| node_context
node_outbox_api -->|"creates record"| node_record
node_record -->|"persists atomically"| node_record_repo
node_scheduler -.->|"loads records"| node_record_repo
node_scheduler -.->|"triggers processing"| node_service
node_service -->|"saves records"| node_record_repo
node_service -->|"resolves handlers"| node_routing
node_processor -.->|"invokes handler"| node_routing
node_processor -.->|"applies retries"| node_retry
node_partition -.->|"coordinates work"| node_record_repo
node_handlers -.->|"registers handlers"| node_routing
node_record_repo -->|"implemented by"| node_jdbc
node_record_repo -->|"implemented by"| node_jpa
node_record_repo -->|"implemented by"| node_mongo
node_jdbc -.->|"reads and writes"| node_database
node_jpa -.->|"reads and writes"| node_database
node_mongo -.->|"reads and writes"| node_database
node_handlers -.->|"externalizes to"| node_kafka
node_handlers -.->|"externalizes to"| node_rabbit
node_handlers -.->|"externalizes to"| node_sns
node_kafka -.->|"publishes to"| node_broker
node_rabbit -.->|"publishes to"| node_broker
node_sns -.->|"publishes to"| node_broker
node_service -.->|"emits observations"| node_observability
node_service -.->|"exposes status"| node_actuator

click node_outbox_api "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt"
click node_context "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/context/OutboxContextCollector.kt"
click node_record "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecord.kt"
click node_routing "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt"
click node_scheduler "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxProcessingScheduler.kt"
click node_service "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt"
click node_processor "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/processor/OutboxRecordProcessorChainInvoker.kt"
click node_retry "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/retry/OutboxRetryPolicyFactory.kt"
click node_partition "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/partition/PartitionCoordinator.kt"
click node_record_repo "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt"
click node_jdbc "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt"
click node_jpa "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt"
click node_mongo "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-mongodb/src/main/kotlin/io/namastack/outbox/MongoOutboxRecordRepository.kt"
click node_kafka "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-kafka/src/main/kotlin/io/namastack/outbox/kafka/KafkaOutboxHandler.kt"
click node_rabbit "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-rabbit/src/main/kotlin/io/namastack/outbox/rabbit/RabbitOutboxHandler.kt"
click node_sns "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-sns/src/main/kotlin/io/namastack/outbox/sns/SnsOutboxHandler.kt"
click node_observability "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-observability/src/main/kotlin/io/namastack/outbox/observability/tracing/OutboxObservabilityTracingContextProvider.kt"
click node_actuator "https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-actuator/src/main/kotlin/io/namastack/outbox/OutboxActuatorEndpoint.kt"

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_outbox_api,node_context,node_record,node_routing toneBlue
class node_scheduler,node_service,node_processor,node_retry,node_partition,node_database toneAmber
class node_record_repo,node_jdbc,node_jpa,node_mongo,node_handlers toneMint
class node_broker,node_kafka,node_rabbit,node_sns,node_observability,node_actuator toneRose
class node_app toneIndigo
```

## Components

### Event API

- [Outbox API](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt): `namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt`
- [Context collection](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/context/OutboxContextCollector.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/context/OutboxContextCollector.kt`
- [Outbox record](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecord.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecord.kt`
- [Handler routing](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt`

### Processing Runtime

- [Polling scheduler](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxProcessingScheduler.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxProcessingScheduler.kt`
- [Outbox service](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt`
- [Record processing](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/processor/OutboxRecordProcessorChainInvoker.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/processor/OutboxRecordProcessorChainInvoker.kt`
- [Retry policies](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/retry/OutboxRetryPolicyFactory.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/retry/OutboxRetryPolicyFactory.kt`
- [Partition coordination](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/partition/PartitionCoordinator.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/partition/PartitionCoordinator.kt`

### Persistence

- [Record repository](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt): `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt`
- [JDBC adapter](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt): `namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt`
- [JPA adapter](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt): `namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt`
- [Mongo adapter](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-mongodb/src/main/kotlin/io/namastack/outbox/MongoOutboxRecordRepository.kt): `namastack-outbox-mongodb/src/main/kotlin/io/namastack/outbox/MongoOutboxRecordRepository.kt`

### Delivery and Operations

- **Messaging brokers**
- [Kafka integration](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-kafka/src/main/kotlin/io/namastack/outbox/kafka/KafkaOutboxHandler.kt): `namastack-outbox-kafka/src/main/kotlin/io/namastack/outbox/kafka/KafkaOutboxHandler.kt`
- [RabbitMQ integration](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-rabbit/src/main/kotlin/io/namastack/outbox/rabbit/RabbitOutboxHandler.kt): `namastack-outbox-rabbit/src/main/kotlin/io/namastack/outbox/rabbit/RabbitOutboxHandler.kt`
- [AWS SNS integration](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-sns/src/main/kotlin/io/namastack/outbox/sns/SnsOutboxHandler.kt): `namastack-outbox-sns/src/main/kotlin/io/namastack/outbox/sns/SnsOutboxHandler.kt`
- [Metrics and tracing](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-observability/src/main/kotlin/io/namastack/outbox/observability/tracing/OutboxObservabilityTracingContextProvider.kt): `namastack-outbox-observability/src/main/kotlin/io/namastack/outbox/observability/tracing/OutboxObservabilityTracingContextProvider.kt`
- [Actuator endpoint](https://github.com/namastack/namastack-outbox/blob/main/namastack-outbox-actuator/src/main/kotlin/io/namastack/outbox/OutboxActuatorEndpoint.kt): `namastack-outbox-actuator/src/main/kotlin/io/namastack/outbox/OutboxActuatorEndpoint.kt`

### Other components

- **Spring application**
- **Configured database**
- **Application handlers**

## Connections

- Spring application → Outbox API: schedules event (evidence: `README.md`)
- Outbox API → Context collection: collects context
- Outbox API → Outbox record: creates record (evidence: `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt`)
- Outbox record → Record repository: persists atomically (evidence: `README.md`)
- Polling scheduler → Record repository: loads records
- Polling scheduler → Outbox service: triggers processing
- Outbox service → Record repository: saves records (evidence: `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt`)
- Outbox service → Handler routing: resolves handlers (evidence: `namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt`)
- Record processing → Handler routing: invokes handler
- Record processing → Retry policies: applies retries
- Partition coordination → Record repository: coordinates work
- Application handlers → Handler routing: registers handlers
- Record repository → JDBC adapter: implemented by (evidence: `namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt`)
- Record repository → JPA adapter: implemented by (evidence: `namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt`)
- Record repository → Mongo adapter: implemented by (evidence: `namastack-outbox-mongodb/src/main/kotlin/io/namastack/outbox/MongoOutboxRecordRepository.kt`)
- JDBC adapter → Configured database: reads and writes
- JPA adapter → Configured database: reads and writes
- Mongo adapter → Configured database: reads and writes
- Application handlers → Kafka integration: externalizes to (evidence: `README.md`)
- Application handlers → RabbitMQ integration: externalizes to (evidence: `README.md`)
- Application handlers → AWS SNS integration: externalizes to (evidence: `README.md`)
- Kafka integration → Messaging brokers: publishes to
- RabbitMQ integration → Messaging brokers: publishes to
- AWS SNS integration → Messaging brokers: publishes to
- Outbox service → Metrics and tracing: emits observations
- Outbox service → Actuator endpoint: exposes status
