From d811606b87419ef7181202202506359ec639fce2 Mon Sep 17 00:00:00 2001
From: Alexey Shalaev <75322386+AlexeyShalaev@users.noreply.github.com>
Date: Tue, 27 Oct 2026 19:02:41 +0400
Subject: [PATCH] docs: say when to use it, and when something else fits better

---
 README.md     | 12 ++++++++++++
 docs/index.md | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 3616cba..6cd56af 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,18 @@ The library ships:
 
 The library does **not** provide a Unit-of-Work implementation. The transactional boundary that ties business state with the outbox row (or with the inbox row plus side effects) is owned by the calling service.
 
+## When to use it, and when not
+
+omni-box fits an async Python 3.12+ service that writes to PostgreSQL through SQLAlchemy and talks to Kafka, and wants both halves of the pattern from one library: an outbox relay that keeps each key's events in order across any number of relay processes, and an inbox that deduplicates on the consumer side, with retries, a DLQ, a circuit breaker, Prometheus and OpenTelemetry as pipeline steps.
+
+Something else is probably the better fit when:
+
+- **You are on Django.** [django-outbox-pattern](https://github.com/juntossomosmais/django-outbox-pattern) and [django-jaiminho](https://github.com/loadsmart/django-jaiminho) are built around Django's ORM and transactions. omni-box is async SQLAlchemy only.
+- **You already use FastStream.** [faststream-outbox](https://github.com/modern-python/faststream-outbox) keeps the outbox in a PostgreSQL table and relays through FastStream to Kafka, RabbitMQ, NATS or Redis. omni-box ships a Kafka adapter only; another broker means implementing `EventPublisher` and `EventConsumer` yourself.
+- **You need Python below 3.12, or a database other than PostgreSQL.** omni-box uses PEP 695 generics, and the only repository it ships is for PostgreSQL. The repository protocols let you write your own ([storage adapters](docs/storage_adapters.md)).
+- **CDC is already in your stack.** If Debezium or a similar tool reads your WAL, its outbox routing replaces the polling relay. The inbox half can still be useful on the consumer side.
+- **You want event sourcing**, not just reliable publishing. [eventsourcing](https://github.com/pyeventsourcing/eventsourcing) is built for that.
+
 ## Requirements
 
 - Python **3.12+** (uses PEP 695 generics).
diff --git a/docs/index.md b/docs/index.md
index 4b06d4c..1ff25a8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,6 +11,18 @@
 - [Troubleshooting](troubleshooting.md) — common issues and tuning tips.
 - [API reference](api_reference.md) — public surface re-exported from `omni_box`.
 
+## When to use it, and when not
+
+omni-box fits an async Python 3.12+ service that writes to PostgreSQL through SQLAlchemy and talks to Kafka, and wants both halves of the pattern from one library: an outbox relay that keeps each key's events in order across any number of relay processes, and an inbox that deduplicates on the consumer side, with retries, a DLQ, a circuit breaker, Prometheus and OpenTelemetry as pipeline steps.
+
+Something else is probably the better fit when:
+
+- **You are on Django.** [django-outbox-pattern](https://github.com/juntossomosmais/django-outbox-pattern) and [django-jaiminho](https://github.com/loadsmart/django-jaiminho) are built around Django's ORM and transactions. omni-box is async SQLAlchemy only.
+- **You already use FastStream.** [faststream-outbox](https://github.com/modern-python/faststream-outbox) keeps the outbox in a PostgreSQL table and relays through FastStream to Kafka, RabbitMQ, NATS or Redis. omni-box ships a Kafka adapter only; another broker means implementing `EventPublisher` and `EventConsumer` yourself.
+- **You need Python below 3.12, or a database other than PostgreSQL.** omni-box uses PEP 695 generics, and the only repository it ships is for PostgreSQL. The repository protocols let you write your own ([storage adapters](storage_adapters.md)).
+- **CDC is already in your stack.** If Debezium or a similar tool reads your WAL, its outbox routing replaces the polling relay. The inbox half can still be useful on the consumer side.
+- **You want event sourcing**, not just reliable publishing. [eventsourcing](https://github.com/pyeventsourcing/eventsourcing) is built for that.
+
 ## Installation
 
 ```bash