Engineering reference: the mileage claim checker architecture

The system, by service name

• Compute
• Database
• App integration
• Networking
• Front-end & mobile

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

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

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: claims

PK   claim_id          S   clm_2026_07_09_a3d1
     status            S   open | asked | payable | exported
     fingerprint       S   sha256(claimant|trip_date|from_cell|to_cell)
     claimant          S   sam@example.com
     trip_date         S   2026-07-07
     from_cell         S   geohash7 of the origin
     to_cell           S   geohash7 of the destination
     miles_claimed     N   84.0
     miles_expected    N   41.2
     basis             S   expected 41.2, band +50%, return trip
     ttl               N   epoch, +7 years

GSI  fingerprint-index   PK fingerprint          — the repeat test
GSI  status-index        PK status, SK asked_at  — the escalation sweep

Table: routes

PK   pair              S   geohash7|geohash7, lexically sorted
     miles             N   41.2
     provider          S   which service answered
     fetched_at        S   2026-07-09T18:02:11Z

Sorting the two cells lexically means A-to-B and B-to-A share one cache
entry, which roughly halves the lookups on any out-and-back round.

Table: totals

PK   claimant          S   sam@example.com
SK   period            S   2026-07
     miles             N   412.0
     amount            N   185.40
     claims            N   9

The increment:
  UpdateExpression:    SET miles = miles + :m, amount = amount + :a
  ConditionExpression: attribute_not_exists(exported_at)

Inbound and outbound

• The phone form is static files in S3 behind CloudFront, with an origin access control. There is no login: the link carries a signed staff token, minted once when somebody is added to the staff sheet, and it is the only credential a driver ever handles.
• Function URLs are public by default. Both mc-intake and mc-pay verify an HMAC on the first line of the handler, before parsing and before any database read.
• Answer links in the question email are signed, scoped to one claim, single-use by conditional write, and expire after fourteen days — longer than the approval links elsewhere on this site, because drivers take holidays.
• SMS nudges go through SNS to numbers from the staff sheet only. There is no path by which a number in a claim body becomes a destination.

The model call

• Model: anthropic.claude-haiku-4-5-20251001-v1:0 on Bedrock, used only for resolving a typed place name against the customer and job lists. Everything numeric is code.
• Called at most once per claim, and not at all when both ends came from the recent list or the customer search — which is most claims.
• Output is a JSON schema with a customer id, a job id and a confidence, all nullable. Null produces the short pick-list the claimant sees; it never produces a guess.
• Grounded with the claimant’s own recent sites and the active customer list, so the model chooses from a list rather than inventing an address.
• No tools, no chaining. One call in, one JSON out.

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

All posts