Skip to content
allanninal.dev/build
Collaborate

Part 5 of 7 · Timesheet validator series ~5 min read

How a payroll week gets closed

Everything so far has been about making a sheet correct before anybody needs it. This post is about what happens at the end — the record that gets written, the file payroll actually consumes, and the one report that tells you whether your rules are set anywhere near right.

Key takeaways

  • The system decides what is correct. Payroll pays it. That boundary never moves.
  • Every closed sheet stores the rules it was judged against, not just the outcome.
  • An override is recorded with a name and a reason; the original number is never overwritten.
  • The export is one file per period, regenerable, and byte-identical every time.
  • If more than about one sheet in ten needs a question, the rules are wrong, not the people.

What a closed week holds

FieldExampleWhy it is there
personsam@example.comWho the week belongs to
week_ending2026-07-12The period key, always a Sunday
hours44.0Total, after any answered corrections
overtime4.0Split out, because it is paid differently
rulesbreak 30/6h, OT>40, max 12hWhat it was judged against, stamped
findings1 gap (answered), 1 OT (approved)What was asked and by whom
overridesnoneAny manual change, with a name and a reason
closed_byauto / manager@Who closed it
sourceform / photo / sheetWhich lane it came in through
stateclean / carried / exportedWhere it is in the period

The rules field is the one that is easy to leave out and painful to add later. Overtime thresholds and break rules change, sometimes mid-period, sometimes retroactively. A sheet that stores only its outcome cannot tell you why a week in May was clean under one rule and would not be under today’s. A sheet that stamps its rules can, and that is the difference between a record and a number.

Overrides

Sometimes a manager just needs to change a number: a day was logged against the wrong job and the person has left, a break was genuinely missed and is being paid, an agreement was reached that the system knows nothing about. Overrides exist, and they are additive rather than destructive.

  • The original stays. An override writes a new value alongside the submitted one; it does not replace it. Both are exported, and the export column payroll reads is the effective value.
  • A name and a reason are required. Not a dropdown of four reasons — a free-text line, because the useful reasons are always the ones nobody anticipated.
  • An override is a finding. It appears in the month-end report, counted separately, because a rising override count is the clearest possible signal that a rule in the sheet no longer matches how the business actually runs.
  • Nobody can override their own week. The one hard permission rule in the system, and the only reason it needs a notion of who a manager is at all.

The export

How a payroll period export is built and frozenA vertical chain of five steps entered by a box labelled Period cut-off, which is a date rather than a button. Step one selects the sheets in the period by week ending, using a period index on the DynamoDB sheets table. Step two asks whether any are still open, exiting to Carry forward, where the known hours are paid now. Step three applies overrides to produce an effective value per row. Step four writes the file as one sorted CSV. Step five marks the sheets exported, making them read-only. A note says regenerating an export produces a byte-identical file because the period is a date and not a cursor.AWS ACCOUNTPeriod cut-offa date, not a buttonSheets in the periodby week endingDynamoDB sheetsperiod indexAny still open?Carry forwardknown hours pay nowopenApply overrideseffective value per rowWrite the fileone CSV, sortedMark exportedsheets become read-onlyRegenerating an export produces a byte-identical file. The period is a date, not a cursor.
Fig 1. How the period file is built. The period boundary is a date rather than “everything since last time”, which is why running the export twice cannot produce two different files.
  • Database
  • App integration
  • Security & identity
  • Management
  • Analytics

The report that tells you if this is working

One payroll period summarised in five numbersA horizontal row of five boxes. Sheets: eighty-eight submitted. Clean first time: seventy-nine. Asked: nine sheets generated a question. Needed a manager: three. Overrides: one. A note says the third number is about your rules and the fifth is about whether they still fit.ONE PERIOD, IN FIVE NUMBERSSheets88 submittedClean first time79Asked9 sheetsNeeded a manager3Overrides1The third number is about your rules. The fifth is about whether they still fit.
Fig 2. A month in five numbers. Read the third and fifth together: a lot of questions means the rules are too tight, and a lot of overrides means they no longer describe the business.
  • App integration
  • Machine learning
  • Management
  • People

Nine questions out of eighty-eight sheets is a system doing its job. Thirty would mean a rule is wrong — most often a break rule that does not match how people actually take breaks, or an overtime threshold set at the contracted hours rather than the point where overtime is genuinely payable. The fix is an edit in the rules tab, and the next period will show it.

A rising override count is the more interesting signal, because it means managers are routinely working around the rules rather than fixing them. One a month is normal. Eight a month means the rules tab describes a business that no longer exists, and somebody should spend twenty minutes on it.

Next: what all of this costs to run.

All posts