Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Damaged goods claimer series ~6 min read

A damaged goods claimer on AWS for a few dollars a month

A crate arrives with a corner stoved in. Somebody photographs the broken item, throws the crate in the skip because it is taking up space, and files a claim three days later. The carrier asks whether the outer packaging was damaged. Nobody can say, and the claim is declined. This post walks through a small system designed around those two minutes.

A bunch of tools that are on a table
Photo by Anton Savinov on Unsplash

Key takeaways

  • Photograph the packaging before the contents, and keep the packaging until the claim closes.
  • The deadline usually runs from delivery, not from when the damage was found.
  • Concealed damage has a shorter clock and a weaker position; both are worth knowing at the door.
  • Many claims cost more to file than they recover. Knowing which is a real output.
  • Designed on AWS for about $2 a month.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: damage evidence captured, deadlines tracked, claims assembledThree boxes across the top sit outside the AWS account. On the left, A damaged delivery and its packaging. In the middle, Carrier terms, with their windows and limits. On the right, Whoever files, always a person. Each connects by an arrow to the AWS account container below. Photographs flow down into the account. The applicable window feeds in. A pack and a recommendation go back out. Inside the AWS account are three components in a row. On the left, Evidence capture, taking the packaging first and then the contents. In the middle, the Deadline clock, running from delivery and configured per carrier. On the right, the Claim assembler, producing the pack, the value, and whether it is worth filing. A note at the bottom says the first box has about two minutes and everything else has days.AWS ACCOUNTA damaged deliveryand its packagingCarrier termswindows and limitsWhoever filesa person, alwaysEvidence capturepackaging first,then contentsDeadline clockfrom delivery,per carrierClaim assemblerpack, value,worth filing?photographsthe applicablewindowa pack, and arecommendationThe first box has about two minutes. Everything else has days.
Fig 1. Three things outside the account, three pieces inside it. The asymmetry in the note is the reason the design looks the way it does.
  • Management
  • Front-end & mobile
  • People

The packaging is the case

Every damage claim turns on the same question: was the damage visible from outside, and did anybody note it at delivery? A photograph of a broken item establishes that it is broken. A photograph of a crushed crate with the carrier’s label in frame establishes how and when it got that way.

The packaging is also the thing most likely to be gone. It is bulky, it is in the way, and disposing of it is the natural next action after unpacking. A system that does nothing else but reliably produce the sentence “keep the packaging until this closes” would earn its cost.

What runs (the inside)

  • Evidence capture. A fixed photograph sequence at the door and a hold on the packaging. Part 2.
  • The deadline clock. Which window applies, from when, per carrier and per damage type. Part 3.
  • The claim assembler. Builds the pack, computes the value, and says whether filing is worth the effort. Parts 4 and 5.

One claim, end to end

One damage claim from discovery at delivery to filingA horizontal row of five boxes joined by arrows. Damage seen: at delivery. Five photographs: packaging first. Note annotated: before signing. Deadline set: seven days for this carrier. Filed day two: six hundred and eighty pounds, with the pack. A note says seven days sounds generous and is four working days over a bank holiday weekend.ONE CLAIM, END TO ENDDamage seenat delivery5 photographspackaging firstNote annotatedbefore signingDeadline set7 days, this carrierFiled day 2£680, with the packSeven days sounds generous and is four working days over a bank holiday weekend.
Fig 2. The same system as one line. The note is the reason the deadline is computed rather than remembered.
  • Management
  • Analytics
  • Front-end & mobile

In plain words

A pallet arrives and one corner is visibly crushed. The person receiving opens the app, which walks them through five photographs in a fixed order: the pallet as delivered on the vehicle, the damaged corner with the carrier label readable, the packaging opened, the damaged item, and the item’s own label.

The system generates the wording for the delivery note — damage noted before signature, which is the difference between a claim and an argument — and puts a hold on the packaging: a printed label saying do not dispose until this claim closes, with the reference.

Behind that, the clock starts. This carrier’s terms give seven days from delivery for visible damage, which the system converts into an actual date. The claim pack assembles itself from the photographs, the delivery note, the invoice and the purchase order, and somebody files it on day two after checking that the value is worth the twenty minutes.

Design rules that shaped every decision

  • Photograph the packaging before the contents, in a fixed order, every time.
  • Hold the packaging physically, with a label, until the claim resolves.
  • The deadline runs from delivery unless the carrier’s terms say otherwise.
  • Note the damage on the delivery note before signing, always.
  • A claim is filed by a person. The system assembles and reminds.
  • Say when a claim is not worth filing. That is a useful answer.

Why this shape

Damage claims fail for procedural reasons far more often than for factual ones. The goods were genuinely damaged, the carrier genuinely damaged them, and the claim is declined because it was filed on day nine, or because the delivery note was signed clean, or because nobody can produce a photograph of the outer packaging.

All three of those are preventable by a system that does very little except at exactly the right moments: a fixed photograph sequence at the door, a computed date, and a label on a crate. The clever parts of this problem are not where the value is.

The next four posts walk through each piece: how the evidence gets captured, how the deadline is worked out, which claims are worth filing, and what the claims add up to. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts