Engineering reference: the holiday accrual tracker architecture

The system, by service name

• Compute
• Storage
• Database
• Management

Region and account

• Region: eu-west-2. London, because this is employment data about UK workers and there is no reason for it to leave. Bedrock model availability is checked here rather than assumed; the contract read is the only step that would have to move if the model needed were not present, and it is the only step that is not arithmetic.
• 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: workers

PK   employer_id#worker_id S
SK   ’terms#’ + effective  S   one item per contract version
     leave_year_start      S   MM-DD, or the hire anniversary
     leave_year_source     S   contract | policy | statutory_default
     accrual_rate          N   0.1207 unless the contract is better
     pot_split             M   {four_week, remainder, contractual}
     recovery_term         BOOL a written term allowing deduction on leaving
     evidence_key          S   the contract itself, not a summary

leave_year_source is stored because the statutory default is per-worker
and the other two are per-business. A system that only stores the date
cannot tell you which of its 46 year ends it invented.

Table: ledger

PK   employer_id#worker_id S
SK   period_end#seq        S   append-only; seq disambiguates corrections
     kind                  S   accrual | deduction | carry_in | carry_out |
                               adjustment | payout
     hours                 N   signed
     pot                   S   four_week | remainder | contractual
     leave_year            S   the window this line belongs to
     expires_on            S   set on carry_in lines only
     reason                S   sickness | family_leave | employer_failure |
                               agreement | leave_year_moved
     inputs                M   hours worked, rate, rounding, source file

Nothing in this table is ever updated or deleted. A correction is an
adjustment line carrying the same period_end and a later seq, so the
balance as at any past date is still recoverable.

Table: bookings

PK   employer_id#worker_id S
SK   booking_id            S
     from_date             S
     to_date               S
     hours                 N
     state                 S   requested | reserved | taken | cancelled
     deducted_seq          S   the ledger line, set when state becomes taken

state and deducted_seq together are the invariant: a booking in state
taken must name a ledger line, and a ledger deduction must name a
booking. A nightly check that both directions hold is four lines of
code and catches every partial write this system can produce.

Inbound and outbound

• Timesheets are parsed, not read by a model. They are the largest files here and they are fixed-header exports from payroll or a rota tool. A model would be slower and would occasionally invent an hour.
• Contracts are read once per version. A variation is a new item under the same worker, never an edit, so a balance calculated last March still knows which terms applied then.
• Leave requests arrive over an API and the reservation is a conditional write. Two managers approving the same week is a condition failure rather than a lock.
• Balances go out monthly by SES, to every worker, with what expires and when. This is the operational feature that closes the employer-failure carry-over route.

The model call

• One call per contract version. Nothing per shift, per period, per booking or per balance query. All of those are arithmetic.
• A mid-tier model. The extraction is four fields and a quotation for each, out of a long document. Length is not the same as difficulty.
• Every extracted term comes back with the clause it came from, verbatim and with a page reference, because a disputed balance is settled by reading the clause rather than by trusting the field.
• Absent means null, never a default. A contract that says nothing about recovering overtaken leave must produce null, not false and certainly not true. Null is the answer that stops the leaver job making a deduction.
• No model touches accrual, deduction, carry-over or the payout. Every one of them has to be re-runnable years later and explainable to somebody who disagrees with the result.

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

All posts