# mustafaa428/tinyoutbox architecture

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

- Interactive diagram: https://gitdiagram.com/mustafaa428/tinyoutbox
- Repository: https://github.com/mustafaa428/tinyoutbox

## Overview

TinyOutbox is a .NET transactional outbox and inbox library. Its main workflow atomically enqueues an event with application data, then a hosted worker polls pending records, publishes them to RabbitMQ, and updates retry or completion state. Consumers can use the inbox service for idempotent execution; hosted cleanup removes expired records. PostgreSQL/Dapper and EF Core provide alternative storage implementations. The README documents these capabilities; relationships among sampled components are shown where source references support them.

Main entry points: [`TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs`](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs) (Outbox worker), [`TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs`](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs) (RabbitMQ publisher), [`TinyOutbox/TinyOutbox.Core/Services/Abstract/IOutboxStorage.cs`](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IOutboxStorage.cs) (Outbox storage contract), [`TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs`](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs) (Cleanup worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core messaging"]
  node_outbox_api["Outbox API<br/>[ITinyOutbox.cs]"]
  node_outbox_service["Outbox service"]
  node_message_model["Outbox message<br/>[OutboxMessage.cs]"]
  node_outbox_contract["Outbox storage contract<br/>[IOutboxStorage.cs]"]
  node_inbox_service["Inbox service"]
  node_inbox_contract["Inbox storage contract<br/>[IInboxStorage.cs]"]
  node_publisher_contract["Publisher contract"]
end

subgraph group_hosting["Hosted processing"]
  node_worker["Outbox worker"]
  node_cleanup_worker["Cleanup worker"]
  node_options["Worker options<br/>[OutboxOptions.cs]"]
  node_hosting_setup["Hosting setup"]
end

subgraph group_storage["Storage providers"]
  node_ef_outbox["EF outbox storage"]
  node_ef_inbox["EF inbox storage"]
  node_ef_mapping["EF model mapping"]
  node_ef_setup["EF registration"]
  node_pg_outbox["PostgreSQL outbox"]
  node_pg_inbox["PostgreSQL inbox"]
  node_pg_options["PostgreSQL options"]
  node_pg_setup["PostgreSQL registration"]
end

subgraph group_transport["Broker transport"]
  node_rabbit_publisher["RabbitMQ publisher"]
  node_rabbit_options["RabbitMQ options"]
  node_rabbit_setup["RabbitMQ registration"]
end

node_application(("Application"))
node_db[("Relational database")]
node_broker["RabbitMQ broker"]
node_consumer(("Message consumer"))

node_application -->|"enqueues atomically"| node_outbox_api
node_outbox_service -->|"implements"| node_outbox_api
node_outbox_service -->|"writes through"| node_outbox_contract
node_outbox_service -->|"creates"| node_message_model
node_worker -->|"fetches and updates"| node_outbox_contract
node_worker -->|"publishes through"| node_publisher_contract
node_worker -->|"reads settings"| node_options
node_worker -.->|"publishes via"| node_rabbit_publisher
node_rabbit_publisher -->|"implements"| node_publisher_contract
node_rabbit_publisher -->|"reads settings"| node_rabbit_options
node_rabbit_publisher -->|"publishes messages"| node_broker
node_broker -->|"delivers messages"| node_consumer
node_consumer -->|"requests deduplication"| node_inbox_service
node_inbox_service -->|"checks and records"| node_inbox_contract
node_cleanup_worker -->|"purges expired records"| node_outbox_contract
node_cleanup_worker -->|"purges expired records"| node_inbox_contract
node_cleanup_worker -->|"reads settings"| node_options
node_hosting_setup -->|"registers"| node_worker
node_hosting_setup -->|"registers"| node_cleanup_worker
node_ef_outbox -->|"implements"| node_outbox_contract
node_ef_inbox -->|"implements"| node_inbox_contract
node_ef_setup -->|"registers"| node_ef_outbox
node_ef_setup -->|"registers"| node_ef_inbox
node_ef_mapping -->|"maps model"| node_message_model
node_ef_outbox -.->|"reads and writes"| node_db
node_ef_inbox -.->|"reads and writes"| node_db
node_pg_outbox -->|"implements"| node_outbox_contract
node_pg_inbox -->|"implements"| node_inbox_contract
node_pg_outbox -->|"uses settings"| node_pg_options
node_pg_inbox -->|"uses settings"| node_pg_options
node_pg_setup -->|"registers"| node_pg_outbox
node_pg_setup -->|"registers"| node_pg_inbox
node_pg_outbox -->|"queries and updates"| node_db
node_pg_inbox -->|"queries and updates"| node_db
node_rabbit_setup -->|"registers"| node_rabbit_publisher
node_rabbit_setup -->|"configures"| node_rabbit_options

click node_outbox_api "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/ITinyOutbox.cs"
click node_outbox_service "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs"
click node_message_model "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/OutboxMessage.cs"
click node_outbox_contract "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IOutboxStorage.cs"
click node_inbox_service "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyInboxService.cs"
click node_inbox_contract "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IInboxStorage.cs"
click node_worker "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs"
click node_cleanup_worker "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs"
click node_options "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxOptions.cs"
click node_hosting_setup "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/TinyOutboxExtensions.cs"
click node_ef_outbox "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreOutboxStorage.cs"
click node_ef_inbox "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreInboxStorage.cs"
click node_ef_mapping "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/ModelBuilderExtensions.cs"
click node_ef_setup "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs"
click node_pg_outbox "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs"
click node_pg_inbox "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs"
click node_pg_options "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxOptions.cs"
click node_pg_setup "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlExtensions.cs"
click node_publisher_contract "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IMessagePublisher.cs"
click node_rabbit_publisher "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs"
click node_rabbit_options "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqOutboxOptions.cs"
click node_rabbit_setup "https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqExtensions.cs"

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_outbox_service,node_message_model,node_outbox_contract,node_inbox_service,node_inbox_contract,node_publisher_contract toneBlue
class node_worker,node_cleanup_worker,node_options,node_hosting_setup,node_db toneAmber
class node_ef_outbox,node_ef_inbox,node_ef_mapping,node_ef_setup,node_pg_outbox,node_pg_inbox,node_pg_options,node_pg_setup toneMint
class node_rabbit_publisher,node_rabbit_options,node_rabbit_setup toneRose
class node_application,node_broker,node_consumer toneIndigo
```

## Components

### Core messaging

- [Outbox API](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/ITinyOutbox.cs): `TinyOutbox/TinyOutbox.Core/Services/Abstract/ITinyOutbox.cs`
- [Outbox service](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs): `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs`
- [Outbox message](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/OutboxMessage.cs): `TinyOutbox/TinyOutbox.Core/OutboxMessage.cs`
- [Outbox storage contract](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IOutboxStorage.cs): `TinyOutbox/TinyOutbox.Core/Services/Abstract/IOutboxStorage.cs`
- [Inbox service](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyInboxService.cs): `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyInboxService.cs`
- [Inbox storage contract](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IInboxStorage.cs): `TinyOutbox/TinyOutbox.Core/Services/Abstract/IInboxStorage.cs`
- [Publisher contract](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Core/Services/Abstract/IMessagePublisher.cs): `TinyOutbox/TinyOutbox.Core/Services/Abstract/IMessagePublisher.cs`

### Hosted processing

- [Outbox worker](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs): `TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs`
- [Cleanup worker](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs): `TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs`
- [Worker options](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/OutboxOptions.cs): `TinyOutbox/TinyOutbox.Hosting/OutboxOptions.cs`
- [Hosting setup](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Hosting/TinyOutboxExtensions.cs): `TinyOutbox/TinyOutbox.Hosting/TinyOutboxExtensions.cs`

### Storage providers

- [EF outbox storage](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreOutboxStorage.cs): `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreOutboxStorage.cs`
- [EF inbox storage](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreInboxStorage.cs): `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreInboxStorage.cs`
- [EF model mapping](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/ModelBuilderExtensions.cs): `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/ModelBuilderExtensions.cs`
- [EF registration](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs): `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs`
- [PostgreSQL outbox](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs): `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs`
- [PostgreSQL inbox](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs): `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs`
- [PostgreSQL options](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxOptions.cs): `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxOptions.cs`
- [PostgreSQL registration](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlExtensions.cs): `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlExtensions.cs`

### Broker transport

- [RabbitMQ publisher](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs): `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs`
- [RabbitMQ options](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqOutboxOptions.cs): `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqOutboxOptions.cs`
- [RabbitMQ registration](https://github.com/mustafaa428/tinyoutbox/blob/main/TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqExtensions.cs): `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqExtensions.cs`

### Other components

- **Application**
- **Relational database**
- **RabbitMQ broker**
- **Message consumer**

## Connections

- Application → Outbox API: enqueues atomically (evidence: `README.md`)
- Outbox service → Outbox API: implements (evidence: `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs`)
- Outbox service → Outbox storage contract: writes through (evidence: `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs`)
- Outbox service → Outbox message: creates (evidence: `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyOutboxService.cs`)
- Outbox worker → Outbox storage contract: fetches and updates (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs`)
- Outbox worker → Publisher contract: publishes through (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs`)
- Outbox worker → Worker options: reads settings (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxBackgroundWorker.cs`)
- Outbox worker → RabbitMQ publisher: publishes via
- RabbitMQ publisher → Publisher contract: implements (evidence: `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs`)
- RabbitMQ publisher → RabbitMQ options: reads settings (evidence: `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs`)
- RabbitMQ publisher → RabbitMQ broker: publishes messages (evidence: `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqMessagePublisher.cs`)
- RabbitMQ broker → Message consumer: delivers messages (evidence: `README.md`)
- Message consumer → Inbox service: requests deduplication (evidence: `README.md`)
- Inbox service → Inbox storage contract: checks and records (evidence: `TinyOutbox/TinyOutbox.Core/Services/Concrate/TinyInboxService.cs`)
- Cleanup worker → Outbox storage contract: purges expired records (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs`)
- Cleanup worker → Inbox storage contract: purges expired records (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs`)
- Cleanup worker → Worker options: reads settings (evidence: `TinyOutbox/TinyOutbox.Hosting/OutboxCleanupWorker.cs`)
- Hosting setup → Outbox worker: registers (evidence: `TinyOutbox/TinyOutbox.Hosting/TinyOutboxExtensions.cs`)
- Hosting setup → Cleanup worker: registers (evidence: `TinyOutbox/TinyOutbox.Hosting/TinyOutboxExtensions.cs`)
- EF outbox storage → Outbox storage contract: implements (evidence: `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/EfCoreOutboxStorage.cs`)
- EF inbox storage → Inbox storage contract: implements (evidence: `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs`)
- EF registration → EF outbox storage: registers (evidence: `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs`)
- EF registration → EF inbox storage: registers (evidence: `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/TinyOutboxEfCoreExtensions.cs`)
- EF model mapping → Outbox message: maps model (evidence: `TinyOutbox/TinyOutbox.Storage.EntityFrameworkCore/ModelBuilderExtensions.cs`)
- EF outbox storage → Relational database: reads and writes
- EF inbox storage → Relational database: reads and writes
- PostgreSQL outbox → Outbox storage contract: implements (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs`)
- PostgreSQL inbox → Inbox storage contract: implements (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs`)
- PostgreSQL outbox → PostgreSQL options: uses settings (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs`)
- PostgreSQL inbox → PostgreSQL options: uses settings (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs`)
- PostgreSQL registration → PostgreSQL outbox: registers (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlExtensions.cs`)
- PostgreSQL registration → PostgreSQL inbox: registers (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlExtensions.cs`)
- PostgreSQL outbox → Relational database: queries and updates (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlOutboxStorage.cs`)
- PostgreSQL inbox → Relational database: queries and updates (evidence: `TinyOutbox/TinyOutbox.Storage.PostgreSql/PostgreSqlInboxStorage.cs`)
- RabbitMQ registration → RabbitMQ publisher: registers (evidence: `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqExtensions.cs`)
- RabbitMQ registration → RabbitMQ options: configures (evidence: `TinyOutbox/TinyOutbox.Transport.RabbitMQ/RabbitMqExtensions.cs`)
