Engineering reference: the pension enrolment assessor architecture

The system, by service name

• Compute
• Storage
• Database
• App integration
• Analytics

Region and account

• Region: eu-west-1. Ireland rather than London, because staff messages arrive by email and SES inbound receipt rules are the binding constraint, as elsewhere in this series. The data is payroll and pension data about UK staff, so confirm the transfer position with whoever advises you on data protection before relying on this choice; every other step here is arithmetic and would run anywhere.
• 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: assessments

PK   org_id#worker_id        S
SK   period_start#run_id     S   one row per worker per pay run
     frequency               S   weekly | fortnightly | four_weekly | monthly
     paid_pence              N   earnings payable in the period
     age_on_assessment       N   from date of birth, on the day
     thresholds              S   tax_year#frequency row that was applied
     category                S   eligible_jobholder | non_eligible_jobholder |
                                 entitled_worker | active_member | outside
     duty_id                 S   set where this assessment opened a duty
     supersedes              S   the assessment a corrected pay run replaced

paid_pence is compared against the published figure for its frequency,
never against the annual trigger divided in code. The gap between 192.00
and 192.31 is a real worker in a real week, and comparing floats in
pounds finds new ways to be wrong about it.

Table: duties

PK   org_id#worker_id        S
SK   kind#arose_on           S   enrol | opt_in | join | postpone | refund |
                                 re_enrol
     arose_on                S   the date the duty arose, written once
     due_by                  S   from arose_on and the dated rules row
     source                  S   the assessment or message that opened it
     deferral_date           S   postpone only, at most three months on
     decided_by              S   postponements and exceptions: a person
     evidence                M   {provider_ack, letter_sent, payroll_run}
     state                   S   open | done | missed | superseded

arose_on is written when the duty opens and never recomputed. A re-issued
pay run can change the week a worker crossed the trigger, and a date
derived on demand would move a deadline behind a letter already sent. A
genuine change supersedes the duty, with a reason, instead.

Table: messages

PK   org_id#worker_id        S
SK   received_at#message_id  S
     kinds                   SS  leave | join | change | question
     notice_form             S   signed | statement | none
     confidence              S   high | low; low always routes to a person
     leaving_type            S   opt_out | cease; set by code, from dates
     routed_to               S   scheme_process | payroll | person
     template_id             S   the reviewed reply that was sent
     model_id                S

leaving_type is deliberately not a model output. The model says a worker
wants to leave; the enrolment record says whether the opt-out period is
still open. Two fields written by two pieces of code is what stops a
confident classification from deciding a refund.

Inbound and outbound

• Payroll exports are parsed, not read by a model. A weekly export is a fixed-header file with a row per worker, and assessing it is a comparison against a threshold row. A model has nothing to add and a decimal point to lose.
• Messages arrive by email or the pension form and both land in the same function. A message sent to a site manager is forwarded to the same address, so the route does not depend on who a worker happened to ask.
• Everything outbound is a template. Enrolment letters, postponement notices and every reply to a message are SES templates, reviewed once. The notify role can send named templates and nothing else.
• Nobody is enrolled or opted out automatically. The system raises instructions for the payroll and the provider, and holds each duty open until confirmation of each part comes back.

The model call

• One call per message. Nothing per worker, per pay run or per assessment. Assessment is a comparison.
• A small, fast model. Four kinds and two presence checks from two or three sentences is classification, not reasoning.
• Multi-label, with leaving dominant. A message can be a question and a wish to leave at once, and routing treats any leaving signal as leaving.
• The model writes no text a worker sees. Its output is a JSON object of kinds, a notice-form field and a confidence. Replies are selected from templates by code.
• Absent means null. A message that cannot be matched to a worker, or whose intent is unclear, returns null and low confidence and goes to a person. A guessed worker id is worse than none.

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

All posts