How to Build a Logistics Management System That Handles Duplicate Events

A driver marks a delivery as completed, but the dispatcher still sees it as in transit. A carrier webhook retries after a timeout, and the warehouse receives the same shipment update twice. These failures often originate in how a logistics backend processes concurrent requests, retries, and events from external systems.

A Logistics Management System needs more than shipment CRUD endpoints. It must maintain a consistent view of orders, vehicles, drivers, and delivery status while multiple services update the same shipment. This article explores an event-driven design using Node.js, PostgreSQL, and AWS SQS, with practical controls for duplicate events and out-of-order updates. For a broader look at logistics management software and supply chain workflows, the business requirements are closely connected to these engineering decisions.

Context and Setup

A logistics backend typically receives updates from a dispatch application, a driver mobile app, warehouse software, and carrier APIs. Each source may report a different part of the same shipment's lifecycle.

Consider a shipment moving through created, assigned, picked_up, in_transit, and delivered. If two consumers process updates concurrently, a delayed in_transit event could overwrite a newer delivered state unless the application explicitly protects the transition.

For this implementation, assume the following components:

• Node.js API: accepts dispatch commands and external status updates.
• PostgreSQL: stores authoritative shipment state and processed event identifiers.
• AWS SQS: buffers asynchronous events between services.
• Worker service: validates and applies shipment updates.
• Observability: records event IDs, shipment IDs, processing failures, and retry counts.

This is not merely a theoretical concern. According to the AWS SQS documentation, standard queues provide at-least-once delivery, so a consumer may receive a message more than once. The application must account for duplicates rather than assume every event is unique.

Designing a Logistics Management System Around Reliable Events

The central design principle is to treat every incoming event as an untrusted state-change request, not as permission to overwrite the current shipment record.

Step 1: Define valid shipment transitions

Start by expressing the shipment lifecycle as a state machine. A delivery should not move from delivered back to in_transit because an old carrier notification arrived late.

1. Define permitted transitions for each shipment status.
2. Reject transitions that contradict the current state.
3. Track event timestamps and source sequence numbers where available.
4. Separate shipment status from independent facts, such as a driver's location or a proof-of-delivery document.

Do not use timestamps alone to establish ordering. Different systems can have clock drift, and a newer timestamp does not necessarily represent a newer business event. Prefer a trusted source sequence number or an explicit version check when the integration supports one.

Step 2: Make event processing idempotent

Idempotency means processing the same event multiple times produces the same business outcome as processing it once.

Create a unique constraint on the event identifier in PostgreSQL. Then record the event and update the shipment inside one database transaction.

-- Why: the unique key prevents the same event being applied twice.
CREATE TABLE processed_shipment_events (
    event_id TEXT PRIMARY KEY,
    shipment_id UUID NOT NULL,
    processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Why: reject duplicate IDs without creating another record.
INSERT INTO processed_shipment_events (event_id, shipment_id)
VALUES ($1, $2)
ON CONFLICT (event_id) DO NOTHING
RETURNING event_id;

In the Node.js worker, check whether the insert returned a row. If it did not, the event was already recorded, so the worker can acknowledge the duplicate without repeating the business operation.

If it did, validate and update the shipment within the same transaction. Roll back both changes if validation or the shipment update fails. Otherwise, a crash could leave an event marked as processed even though its status change never committed.

This pattern protects database state, but it does not automatically make external side effects, such as sending an SMS or issuing a refund, exactly once. Use a transactional outbox for downstream notifications and give each downstream operation its own idempotency key.

Step 3: Handle stale updates and retries explicitly

Deduplication solves repeated delivery of the same event ID. It does not solve two distinct events arriving in the wrong order.

1. Include a shipment version or source sequence number in each update where possible.
2. Apply conditional database updates so a stale version cannot overwrite a newer one.
3. Retry transient database and network failures with bounded exponential backoff and jitter.
4. Route repeatedly failing messages to a dead-letter queue for investigation and controlled replay.

For example, a conditional update can prevent a worker from overwriting a newer shipment version:

-- Why: update only when the expected version still matches.
UPDATE shipments
SET status = $1,
    version = version + 1
WHERE id = $2
  AND version = $3
  AND status <> 'delivered'
RETURNING id, status, version;

Here, $3 is the version read by the worker before attempting the update. If no row is returned, the worker must re-read the shipment and decide whether the event is stale, invalid, or eligible for another attempt.

The trade-off is additional database coordination and more complex failure handling. For low-volume systems, synchronous processing may be simpler. For integrations that generate frequent updates, a queue isolates API availability from downstream processing, but it introduces eventual consistency and requires monitoring of queue age and retry volume.

Real-World Application

At Oodles, the Advaya MVP addressed fleet and driver operations through a driver mobile application and an administrative panel. Its documented capabilities included DOT inspections, hours-of-service (HOS) logs, live truck and driver status, location sharing, and communication.

These capabilities illustrate why a logistics backend must coordinate operational records from different interfaces. A driver's inspection submission, a status update, and an administrator's view are distinct interactions that need a consistent underlying record.

The documented project scope covered five operational capabilities across the driver and administrative workflows. No verified latency, throughput, or percentage-improvement figures are available for this project, so none are claimed here.

For teams extending a fleet platform into a larger Logistics Management System, the next engineering step is to define event contracts, establish authoritative ownership of each field, and test duplicate and out-of-order updates before adding more integrations. Explore Oodles for more information about its software engineering work.

Conclusion: Key Takeaways

• Model shipment status explicitly: valid transitions prevent delayed events from reversing completed operations.
• Enforce idempotency in the database: unique event IDs protect against duplicate processing across worker retries.
• Use optimistic concurrency: version checks prevent concurrent updates from silently overwriting each other.
• Separate transactions from side effects: transactional outbox patterns help coordinate database changes with notifications.
• Monitor asynchronous processing: queue age, retry counts, dead-letter messages, and stale-event rejections reveal operational problems.

If you are building event-driven logistics infrastructure, share your approach to shipment ordering, carrier retries, or state reconciliation in the comments.

For help designing a Logistics Management System, contact the Oodles team to discuss your integration and architecture requirements.

Frequently Asked Questions

1. What is a Logistics Management System?

A Logistics Management System coordinates shipment planning, dispatch, vehicle and driver operations, tracking, and delivery records. It connects operational applications and external logistics providers so teams can manage shipment progress and respond to exceptions using consistent information.

2. Should a logistics backend use REST APIs or event-driven architecture?

REST APIs work well for commands and immediate queries, such as assigning a driver or retrieving shipment status. Event-driven architecture is useful for asynchronous updates from carriers, warehouses, and tracking services. Many production systems combine both approaches rather than choosing only one.

3. How do you prevent duplicate shipment updates?

Assign each event a stable identifier and enforce uniqueness in the database. Process the event record and shipment-state change in one transaction. This makes duplicate deliveries safe to acknowledge without repeating the same database operation.

4. How can developers handle out-of-order tracking events?

Use source sequence numbers or shipment versions to determine whether an update is stale. Apply conditional database updates and validate permitted state transitions. If the event cannot be safely applied, record the reason and reconcile it instead of blindly overwriting the current status.

5. Which technologies are suitable for a Logistics Management System?

Node.js can handle API and asynchronous worker workloads, PostgreSQL can maintain transactional shipment records, and AWS SQS can buffer events between services. The appropriate stack depends on integration volume, ordering requirements, operational skills, infrastructure costs, and recovery requirements.