Engineering reference: the packaging data reporter architecture

The system, by service name

• Compute
• Storage
• Database

Region and account

• Region: eu-west-2. London, because the scheme is a UK one and the nation split it reports on is a UK concept. Bedrock model availability is checked here rather than assumed; the specification read is the only step that would have to move, and every other step is multiplication.
• 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: components

PK   org_id#product_code S
SK   component_id        S   primary | secondary | transit | shipment + seq
     materials           L   [{material, portion}] — a list, not a field
     activity            S   brand_owner | filler | importer | distributor |
                             seller | none
     activity_basis      S   what established it, and the document
     counterparty        S   who reports it instead, when activity is none
     intra_group         BOOL true where it never reached the market
     assessed_under      S   the rules version that produced the activity

materials is a list because a card sleeve with a plastic window is two
materials in fixed proportions, and they are charged differently. A
single material field forces a lie on every composite in the range.

Table: weights

PK   org_id#product_code#component_id S
SK   established_on                   S   append-only; newest wins
     grams                            N   per unit, empty packaging
     method                           S   supplier_spec | weighed | sampled
     sample                           M   {n, mean, spread} when sampled
     evidence_key                     S   the spec, the weighing or sample sheet
     superseded_reason                S   why this replaced the previous figure

Weights are versioned by date rather than overwritten, because a period
already submitted used the figure that was current then. A supplier
spec arriving in March does not retrospectively change last year’s
tonnage; it starts a new version and the reconciliation explains it.

Table: periods

PK   org_id#period       S   e.g. 2026-H1
SK   version#row_id      S   version 1 is never edited
     material            S
     split               S   household | non_household
     nation              S   set on household rows only
     tonnes              N
     source_lines        N   how many sales lines contributed
     weight_versions     L   the weight records this row multiplied
     state               S   draft | frozen | submitted | superseded
     variance_note       S   set where the reconciliation flagged a move

weight_versions is what makes the audit trace in part 5 a query rather
than an investigation. Without it, a submitted tonne can name the sales
lines behind it but not the gram figure it was multiplied by, and the
trail stops one step short of the document.

Inbound and outbound

• Sales exports are parsed, not read by a model. They are millions of fixed-header rows a month and they are the largest thing this system touches. A model over them would cost more than the fees being calculated.
• Specifications arrive by upload or mailbox and both land in the same function. A supplier’s PDF drawing and a supplier’s one-line email answer are the same document as far as extraction is concerned, and the email is more common.
• An incomplete specification produces a chase, not a guess. The missing field goes on a list ranked by the tonnage currently resting on an estimate, which is the most useful output of the first year.
• Nothing is submitted automatically. The close produces a file and a pack; a person files it, because a submission is a legal statement and pressing send is a decision.

The model call

• One call per specification document. Nothing per unit, per sales line, per product or per period. Tonnage is a multiplication and a sum.
• A mid-tier model. Material, component and grams out of a short document with unpredictable formatting is extraction, not reasoning.
• Units are extracted, never converted by the model. A spec quoting 0.021 kg comes back as 0.021 and kg, and the conversion happens in code. A model asked to normalise will occasionally move a decimal point, and a decimal point here is a factor of ten across a million units.
• Composites come back as a list. The prompt asks for material portions rather than a material, because the honest answer for half a range is two materials.
• Absent means null. A spec that does not state a weight must produce null, which routes the component to the chase list. A plausible number here is indistinguishable from a real one three years later.

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

All posts