Pub/Sub Design for Logistics Delay Notices: Claude Code Review Workflow

A logistics dispatcher may update one ETA in a dispatch table and accidentally trigger email, LINE, dashboard history, and customer service follow-up at the same time. If the Pub/Sub consumer crashes after sending the email but before acking the message, the event may arrive again. The customer sees two delay notices and calls to ask which one is correct. This article turns that failure into a practical Claude Code review workflow for logistics teams.

Key Points

Logistics Pub/Sub design starts with customer communication, not with a topic name. Decide which ETA change creates an external notice, which change only updates the dashboard, and which case must wait for a dispatcher. Claude Code can draft the event map, but humans decide customer promises, compensation language, and privacy boundaries.

Workflow Before Pub/Sub Settings

Before changing subscription settings, draw the path from dispatch CSV to customer notification. Use a small table with shipment ID, status, ETA, channel, template, retry count, and reviewer. The article is for teams that want fewer duplicate notices, shorter customer calls, and a clearer consultation path rather than a generic queue tutorial.

Area	What Claude Code drafts	Human review
Delay event	payload fields, topic name, sample messages	shipper promise, delay reason, personal data
Notification send	idempotency key, retry rule, audit log	customer channel, template wording, compensation
DLQ review	alert fields, replay checklist, owner	whether the notice is still useful
Metrics	duplicate count, DLQ age, customer calls	revenue impact and consultation priority

3 Use Cases

Use case 1: Define delay events

Start with the screens your team already uses: dispatch board, customer portal, delay reason list, and notification templates. Ask Claude Code to identify each event and whether it can go outside the company.

• Input: dispatch CSV columns, ETA changes, delay reasons, customer channel settings.
• Output: event names, payload fields, and send rules for customer notices.
• Human review: check contract wording, customer impact, personal data, and timing.

Use case 2: Stop duplicate notices

Use an idempotency key built from shipmentId, status, ETA, channel, and templateId. Pub/Sub may redeliver messages when ack timing is unclear, so the notification worker needs its own gate before email, LINE, or dashboard history is written.

• Input: shipment ID, notification history, retry count, previous ETA, new ETA.
• Output: duplicate detection rule, skip rule, audit log fields.
• Human review: decide whether a changed ETA means a new notice or a correction.

Use case 3: Make DLQ visible to operations

Dead-letter topics should not become an engineer-only storage area. For logistics teams, a DLQ item may mean that a customer did not receive a delay notice. The operations screen should show shipment ID, oldest age, last error, owner, and whether a manual call already happened.

• Input: retry count, last error, payload reference, customer account, owner.
• Output: DLQ triage table, replay rule, manual contact checklist.
• Human review: decide whether replaying the notice still helps the customer.

Copy-Paste Prompt

Act as a English logistics Pub/Sub notification reviewer.
Goal: prevent duplicate delay notices, stale ETA messages, and forgotten DLQ items.

Review these materials:
- dispatch CSV columns
- delay notice templates
- Pub/Sub topic and subscription names
- retry policy draft
- dead-letter topic draft
- customer notification channels

Return:
1. event names and payload fields
2. idempotency key proposal
3. retryable and non-retryable failure classes
4. DLQ triage table for operations
5. ten test events before production

Rules:
- do not expose customer phone numbers or driver personal data in payloads
- do not send stale ETA notices
- do not send the same idempotency key twice
- send compensation, apology, and contract questions to humans

Working Check Code

// verify-logistics-pubsub.mjs
// No dependencies. Run with: node verify-logistics-pubsub.mjs
const events = [
  {
    shipmentId: "S-1001",
    sequence: 12,
    status: "delayed",
    previousEta: "2026-07-19T16:30:00+09:00",
    eta: "2026-07-19T17:10:00+09:00",
    idempotencyKey: "S-1001:delayed:2026-07-19T17:10:00+09:00",
    channel: "line",
    retryCount: 0,
    dlqTopic: "delay-notice-dlq",
    reviewer: "cs-lead"
  },
  {
    shipmentId: "S-1001",
    sequence: 12,
    status: "delayed",
    previousEta: "2026-07-19T16:30:00+09:00",
    eta: "2026-07-19T17:10:00+09:00",
    idempotencyKey: "S-1001:delayed:2026-07-19T17:10:00+09:00",
    channel: "line",
    retryCount: 1,
    dlqTopic: "delay-notice-dlq",
    reviewer: "cs-lead"
  },
  {
    shipmentId: "S-1002",
    sequence: 5,
    status: "delayed",
    previousEta: "2026-07-19T18:20:00+09:00",
    eta: "2026-07-19T18:00:00+09:00",
    idempotencyKey: "S-1002:delayed:2026-07-19T18:00:00+09:00",
    channel: "email",
    retryCount: 4,
    dlqTopic: "",
    reviewer: ""
  }
];

const seen = new Set();
const problems = [];

for (const event of events) {
  if (seen.has(event.idempotencyKey)) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "duplicate idempotency key",
      fix: "publish the retry, but skip customer notification"
    });
  }
  seen.add(event.idempotencyKey);

  if (new Date(event.eta) <= new Date(event.previousEta)) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "ETA did not move later",
      fix: "do not send a delay notice; send to human review"
    });
  }

  if (event.retryCount >= 3 && !event.dlqTopic) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "retry limit reached without DLQ",
      fix: "route to delay-notice-dlq and alert the CS lead"
    });
  }

  if (!event.reviewer) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "missing reviewer",
      fix: "require a dispatcher or CS lead before customer send"
    });
  }
}

if (problems.length > 0) {
  console.table(problems);
  process.exitCode = 1;
} else {
  console.log("Pub/Sub delay notification checklist passed.");
}

Pitfall: Common Failure Cases

The biggest failure is treating redelivery as if it were a customer action. Redelivery is a transport behavior; customer notification is a business action. Keep those two layers separate.

First, teams confuse transport retry with customer retry. Pub/Sub can redeliver a message, but the customer should not receive the same email twice. The fix is an idempotency key stored by the notification service.

Second, teams rely on ordering alone. Ordering keys help, but the application still needs to reject old sequence numbers and stale ETAs before external sending.

Third, DLQ is left inside engineering tools. In logistics, that hides a customer communication gap. Move DLQ age and owner into the operations routine.

FAQ

Q. Does exactly-once delivery remove the need for idempotency?\n\nA. No. You still need an application-level guard before email, LINE, or customer portal writes.

Q. Should Pub/Sub messageId be the idempotency key?

A. Usually no. A logistics notice should use business fields such as shipmentId, status, ETA, channel, and templateId so that the same customer-facing notice is recognized even when publishing changes.

Q. Can DLQ messages be replayed in bulk?

A. Not without a human check. A delay notice may become useless after delivery, so replay should inspect current ETA, delivery status, and manual contact history.

Q. Where should readers go next?

A. Teams that need Pub/Sub, Cloud Run, IAM, notification templates, and operational checks reviewed together should start from ClaudeCodeLab training.

What I Verified

For the English version, I kept the article focused on logistics operations, duplicate notices, DLQ review, and a training CTA. I checked the official Google Cloud pages for Pub/Sub overview, subscriptions, retry policy, dead-letter topics, exactly-once delivery, and message ordering. I also checked that this article has one CTA, an internal link, external sources, executable JavaScript, and locale files.