Moving Logistics Integrations onto a Kafka Event Backbone

An anonymous logistics account describing Kafka topics, an adapter layer and domain-by-domain transition, with publication, replay and business-effect limits explicit.

Order-related work depended on several synchronous handoffs

A logistics platform's order-related processing waited on inventory, shipping and CRM calls. A slow CRM path could hold up order processing, while inconsistent retries and limited cross-integration visibility complicated investigation.

Ampity introduced a Kafka event-backbone design with domain topics, a schema registry, tracing and version metadata, and adapters for legacy systems. The transition kept existing databases and partner contracts, with domain-by-domain adoption alongside synchronous integrations. Continuity was a requirement throughout that change.

Decide which work can safely remain pending

Separating downstream work from an immediate request changes what the caller knows. An order may still need an authoritative acceptance decision, while a notification can have a separate pending or failed state.

The decision therefore belongs to each handoff. Define what has been committed, which consumer outcome is required and what the caller may truthfully treat as complete. Changing transport does not settle those business responsibilities.

Use an event backbone without event-sourcing every aggregate

The selected design used Kafka topics for independent consumers of domain facts. Point-to-point queues and a broader CQRS/event-sourcing change were alternatives; the broader change was deferred because of its operating complexity.

The existing databases remained part of the system. Kafka was not thereby the authoritative business database, and a topic was not necessarily a complete event-sourced history. The domain owner still had to define the published fact and the authority for each state transition.

Select a work queue, direct call or retained event stream from the required completion and recovery behavior. Every new integration does not need the same transport or operating model.

The legacy adapter creates a publication boundary

Legacy systems published through an adapter layer while newer components used events directly. The design included schema management and metadata for tracing and version interpretation.

The publication transaction, consumer-group assignment, schema format and compatibility policy are unspecified. An adapter does not establish an atomic handoff between a database update and Kafka publication. An outbox or change-data-capture design must not be inferred from its presence.

Schema compatibility also leaves a business question: can a delayed consumer interpret an older fact correctly and apply it with the right authority? A parseable event is not sufficient evidence of that decision.

Parallel paths need one owner for each effect

The migration sequence placed infrastructure and schema work before order-domain events, followed by shipping and notification work. It used a period of parallel synchronous and event publication before removal of selected synchronous dependencies.

During such a transition, assign one executor to each external or database effect. Retain the operation identity and the authoritative path while work remains in flight. Parallel publication must not silently become duplicate execution.

Stopping a consumer neither retracts its messages nor undoes a completed external effect. Restoring synchronous routing must not repeat work that an event consumer may already have performed. Hold that operation until its earlier outcome is reconciled.

Trace one fact through to its business effect

Start with an authorized read-only review of permitted integration definitions, existing records and retention settings. This worksheet is proposed guidance for a comparable system, not an executed reconciliation from this engagement.

Any later rehearsal requires an authorized isolated environment, synthetic or approved sanitized events, test identities and non-delivering destinations. Prevent real payments, shipments, customer messages and production record changes. Do not replay a production topic into a live destination to prove a general architecture claim.

For a synthetic exercise, interrupt publication after a simulated database update, then repeat a consumer delivery after a simulated destination result. Define the expected pending, duplicate and uncertain states before running it. That fixture would test those selected assumptions, not prove the historical system's behavior.

The case establishes scope rather than a delivery guarantee

This case covers the Kafka backbone, legacy adapters, schema management and staged domain transition. It does not publish measured delivery reliability, faster integrations, complete business-event visibility or a verified ability to reconstruct every historical system state.

Pick a handoff with an explicit completion contract

Choose one integration and record the committed fact, required consumer outcome, permitted pending state and recovery owner. Keep an immediate authoritative decision explicit when the caller needs one.

The asynchronous-boundary decision playbook covers the broader choice between direct calls, queues and event publication. Start with the adapter and parallel-path boundary before expanding a Kafka migration.

Technical reference

Apache Kafka's design documentation distinguishes publication and consumption guarantees and requires cooperation from external destinations for stronger end-to-end semantics. Its log-compaction discussion also explains why retention and compaction affect what can be reconstructed. Neither a Kafka topic nor a replay request proves a completed business effect or the ability to reproduce every historical system state.