Engineering reference: the delivery exception handler architecture

Key takeaways

Single region, single account. Every resource is regional; nothing is global except the IAM roles.
3 Lambda functions, each with its own execution role. No shared role, no wildcards on resources.
2 DynamoDB tables, each keyed so the concurrency story is a condition expression rather than a lock.
One Bedrock model, called once, with a JSON schema it must fill or leave null.
Nothing always-on: no instance, no container, no provisioned capacity.

The system, by service name

Fig 1. The same shape as Part 1 with the service names filled in. Nothing here is new; it is the same three groups, named.

Compute
Database
App integration
Networking

Region and account

Region: us-east-1. Chosen because SES inbound receipt rules exist in only a subset of regions and this one has the widest Bedrock model availability. If your data has to stay elsewhere, check both constraints before moving: inbound SES is the binding one.
Account: one. This is a small system, and a separate account per environment costs more in wiring than it saves. A dev and a prod stack in the same account, with distinct resource prefixes, is the right size here.
Everything is regional. The only global resources are the IAM roles and policies. There is no CloudFront, no global table and no cross-region replication, because nothing here has a latency or durability requirement that would justify them.

Lambda inventory

Function	Trigger	Does	Timeout / memory
`de-ingest`	Function URL, carrier webhooks	Normalises the status, updates last_event_at, raises event-based exceptions	10s / 512 MB
`de-sweep`	EventBridge, hourly	Finds shipments past their silence threshold; runs triage; sets recheck times	300s / 1024 MB
`de-notify`	SQS	Sends the four-line message and the promised follow-up, even with no news	15s / 512 MB

Splitting this into separate functions is not about modularity. It is that only one of them needs Bedrock permissions and only one is reachable from the public internet, and neither of those is true if it is one handler behind a router.

IAM, scoped

Role	Allowed	On
`de-ingest-role`	`dynamodb:UpdateItem`, `dynamodb:PutItem`	Shipments and exceptions
`de-sweep-role`	`dynamodb:Query`, `dynamodb:UpdateItem`, `sqs:SendMessage`	Both tables; the notify queue
`de-notify-role`	`ses:SendEmail`, `dynamodb:UpdateItem`	One verified identity; exceptions

No role has a Resource: “*” on anything that writes, and every GetSecretValue grant names a single secret arn. That is why there is more than one secret rather than one JSON blob with everything in it.

DynamoDB schemas

Table: shipments

PK   tracking_ref      S
     order_id          S
     carrier           S
     service           S   the threshold is keyed on carrier#service
     despatched_at     S
     last_event_at     S   the field the silence sweep queries
     last_status_raw   S   the carrier’s own code and text, kept
     last_status       S   normalised: in_transit | attempted | address | ...
     delivered_at      S   set once; the sweep stops looking
     ttl               N   epoch, +90 days after delivery

GSI1: last_status + last_event_at  — the silence sweep is one query
per active status band, not a scan across every shipment.

Table: exceptions

PK   tracking_ref      S
SK   raised_at         S
     kind              S   silence | attempted | address | refused
                           | never_collected | damaged
     cause             S   internal | customer_data | carrier
     recheck_at        S   set for self-resolving kinds
     contacted_at      S   null if we deliberately did not contact
     promised_update   S   the date we said we would write again
     resolved_at       S
     resolution        S   delivered | reshipped | refunded | traced_lost

`cause` is assigned at triage and is what makes the aggregate report
separate internal failures from carrier ones.

Inbound and outbound

Webhooks where available, polling where not. Poll intervals are proportional to the service’s typical scan gap and stop entirely once delivered.
The silence sweep is a GSI query, not a scan. Shipments are indexed by status and last event time, so the sweep touches only what could be overdue.
Thresholds are recomputed weekly from the observed scan gaps on delivered shipments, per carrier and service, so a carrier changing their scanning practice does not produce a wave of false exceptions.
Order data is read, never written. This system has no write access to the order system.

The model call

There is no model in this system. Status normalisation is a mapping table and detection is a timestamp comparison.
The tempting use is predicting which shipments will fail. It would produce a score over the same data the thresholds already use, with less explainability.
A second tempting use is drafting the customer message. The four lines are a template with two substitutions, and Part 4 is about why the wording should not vary.
Classifying free-text carrier notes into causes is defensible where a carrier sends prose rather than codes, and the raw text is kept beside it.
The cost page assumes none, which is why tracking writes are the only meaningful variable.

Things worth knowing before you build it

Derive silence thresholds from your own delivered shipments per carrier and service. A single global threshold either floods the queue or catches nothing.
Keep the raw carrier status next to the normalised one. New codes appear and the mapping will be wrong sometimes.
Give never-collected a tighter threshold and its own category. It is usually the most common exception and it is entirely internal.
Hold self-resolving exceptions with a recheck time rather than discarding them, or the second failed attempt looks like the first.
Never write a predicted delivery date into a customer message. A promised communication date is a promise you control.

That is the whole system. Seven posts, one diagram at a time, and nothing in it that needs a server.

All posts