How namastack/namastack-outbox works
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: OutboxRecordRepository.kt Record repository · OutboxService.kt Outbox service · Outbox.kt Outbox API · OutboxHandlerRegistry.kt Handler routing
Components 22
Event API
- Outbox API
namastack-outbox-api/src/main/kotlin/io/namastack/outbox/Outbox.kt - Context collection
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/context/OutboxContextCollector.kt - Outbox record
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecord.kt - Handler routing
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/handler/registry/OutboxHandlerRegistry.kt
Processing Runtime
- Polling scheduler
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxProcessingScheduler.kt - Outbox service
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt - Record processing
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/processor/OutboxRecordProcessorChainInvoker.kt - Retry policies
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/retry/OutboxRetryPolicyFactory.kt - Partition coordination
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/partition/PartitionCoordinator.kt
Persistence
- Record repository
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxRecordRepository.kt - JDBC adapter
namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt - JPA adapter
namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt - Mongo adapter
namastack-outbox-mongodb/src/main/kotlin/io/namastack/outbox/MongoOutboxRecordRepository.kt
Delivery and Operations
- Messaging brokers
- Kafka integration
namastack-outbox-kafka/src/main/kotlin/io/namastack/outbox/kafka/KafkaOutboxHandler.kt - RabbitMQ integration
namastack-outbox-rabbit/src/main/kotlin/io/namastack/outbox/rabbit/RabbitOutboxHandler.kt - AWS SNS integration
namastack-outbox-sns/src/main/kotlin/io/namastack/outbox/sns/SnsOutboxHandler.kt - Metrics and tracing
namastack-outbox-observability/src/main/kotlin/io/namastack/outbox/observability/tracing/OutboxObservabilityTracingContextProvider.kt - Actuator endpoint
namastack-outbox-actuator/src/main/kotlin/io/namastack/outbox/OutboxActuatorEndpoint.kt
Other components
- Spring application
- Configured database
- Application handlers
Connections 26
- Spring application → Outbox API: schedules event
README.md - Outbox API → Context collection: collects context
- Outbox API → Outbox record: creates record
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt - Outbox record → Record repository: persists atomically
README.md - Polling scheduler → Record repository: loads records
- Polling scheduler → Outbox service: triggers processing
- Outbox service → Record repository: saves records
namastack-outbox-core/src/main/kotlin/io/namastack/outbox/OutboxService.kt - Outbox service → Handler routing: resolves handlers
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
namastack-outbox-jdbc/src/main/kotlin/io/namastack/outbox/JdbcOutboxRecordRepository.kt - Record repository → JPA adapter: implemented by
namastack-outbox-jpa/src/main/kotlin/io/namastack/outbox/JpaOutboxRecordRepository.kt - Record repository → Mongo adapter: implemented by
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
README.md - Application handlers → RabbitMQ integration: externalizes to
README.md - Application handlers → AWS SNS integration: externalizes to
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