Engineering reference: the card fee auditor architecture

The system, by service name

• Compute
• Storage
• Database
• Security & identity

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

PK   account_id        S
SK   ’#terms’          S   one item per merchant account
     pricing_model     S   blended | ic_plus | ic_plus_plus
     quoted_rate       N   the number on the front of the quote
     quoted_applies_to S   the card type and entry mode it assumes
     auth_fee          N   per authorisation, charged whatever the outcome
     monthly_fixed     M   terminal rental, PCI, gateway, minimum charge
     notice_months     N
     notice_by         S   precomputed, because it is the only date that matters

quoted_applies_to is stored as text because the honest answer is
usually a sentence: consumer debit, chip and PIN, UK-issued.

Table: fees

PK   account_id#period S
SK   fee_code          S   one item per distinct fee on the statement
     category          S   interchange | scheme | acquirer | fixed
     basis             S   per_txn | pct_of_value | monthly | annual
     amount            N
     txn_count         N   what it was charged on, where the statement says
     value_charged     N
     matched_rate      N   from the contract, or null if the fee is not in it
     downgrade_reason  S   corporate | international | keyed | data_missing | none

category is the field the whole page turns on: interchange cannot be
negotiated, acquirer margin can, and mixing them makes every
comparison meaningless.

Inbound and outbound

• Statements arrive by upload or by mailbox and both land in the same function. Nothing depends on an acquirer portal that could change or be withdrawn.
• Transaction exports are parsed, not read by a model. They are fixed-header CSV, they are large, and a model would be both slower and less accurate than a parser.
• The PAN is dropped at ingest. The card type and entry mode are what the analysis needs; keeping the number would put this system in PCI scope for no benefit.
• The report waits for the monthly close, because an effective rate computed on a partial month is the number that starts an argument you then lose.

The model call

• Two calls, both per document. One per contract or rate change letter, one per statement. Nothing per transaction.
• A capable model for statements, deliberately. These are the worst documents in the series — multi-column, abbreviated, often scanned — and cheap extraction produces confidently wrong fee bases.
• A JSON schema with nulls allowed. A fee the model cannot categorise becomes a question for a human rather than a guess, because guessing interchange as margin inverts the conclusion.
• The rate arithmetic is arithmetic. Total fees over total value, per category. No model is asked to compute or judge a percentage.
• Downgrade causes come from the transaction data, not from the model. The statement rarely says why; the card type and entry mode do.

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

All posts