WRITING / THE DESIGN-DECISION FAQ

The design-decision FAQ

Every box in my systems has a why behind it. Each entry names the constraint, the options rejected, and the cost accepted.

Nº 01

Why both Kafka and RabbitMQ?

THE CONSTRAINT

A multi-agent platform behind a live commerce system: agent steps had to stay ordered per conversation, model calls could be slow, and any failed action needed retries that never blocked the user-facing flow.

OPTIONS REJECTED

Synchronous calls between services — any slow model call becomes a user-facing timeout across the whole flow.

One broker for both jobs — Kafka's retry story and RabbitMQ's ordering story are each the weak half of the other tool.

THE DECISION

In a synchronous chain, the user's request waits on the model — slow model, frozen user. With pub/sub, the request is acknowledged instantly, the heavy work runs in the background, and the result returns through the notify step. Kafka carries the ordered event streams — the timeline of what happened, in order, replayable. RabbitMQ carries work distribution — retries, backoff, and dead-letter queues for actions that fail. Nothing blocks; the legacy platform never learned the agents existed.

COST ACCEPTEDTwo brokers to operate and reason about instead of one — paid for with an event-driven onboarding curve for a team of six who had never run one.
Nº 02

Why a database per tenant, not a tenant_id column?

THE CONSTRAINT

Tenants 100x apart in data size sharing one platform, with a product promise of no noisy neighbors — each tenant should feel like the only customer.

OPTIONS REJECTED

tenant_id columns in shared tables — isolation becomes query discipline instead of a physical guarantee, and every engineer is one WHERE clause away from a leak.

One shared cache and one shared deploy — warmth and risk both follow the loudest tenant.

THE DECISION

One proxy owns tenancy and routes each request to that tenant's own database. Hard isolation, per-tenant backups and tuning, cache warmth that belongs to the tenant, and blue-green deploys nobody notices. Isolation, resources, cache warmth and deploys are one problem — this solves it once, at the routing layer. And audits become demonstrations instead of promises: each tenant's data provably lives in its own database.

COST ACCEPTEDMore moving parts: N databases to provision, migrate, and monitor instead of one — automation that had to be built before it paid off.
TEN DECISIONS ARE ON FILE — THE FIRST TWO ARE PUBLISHED HERE. THE REST ARE BEING WRITTEN UP.← BACK TO FIELD NOTES