ShiftPay

New Zealand shift workers — nurses, hospitality staff, factory workers, retail — are paid under rules that most employees don't fully understand. PAYE tax is calculated using annualised income brackets, not a flat rate. ACC earner levy applies to all liable earnings. KiwiSaver contributions must match the elected rate. And public holiday Mondayisation rules can change the gross amount entirely.

Penal rates add another layer of complexity: weekend loading, time-and-a-half on public holidays, and alternative holiday credits are all legitimate entitlements — but most workers have no way to verify they were applied correctly. A shift that crosses midnight into a public holiday earns at a different rate for each minute on either side of that boundary.

The tools that exist are either general-purpose calculators requiring manual entry, or payslip verifiers that audit after the fact. Neither gives workers the information they actually need: what should I earn from this shift I'm logging right now?

That's the gap ShiftPay fills. Log a shift, get the gross pay, net pay, and every deduction calculated from the rules — before the payslip arrives.

The intellectual heart of ShiftPay is a singleton service called FinanceEngine. Every pay calculation in the app flows through it. The design choices in this service — iteration over formulas, Rational over Decimal during accumulation, String over float in the database — were each made to solve a real precision problem.

Minute-by-Minute Loop

Most payroll calculators apply a single multiplier to an entire shift. ShiftPay processes each minute independently. This isn't over-engineering — it's the only approach that handles the real edge cases:

• → A shift that starts on a regular weekday and ends on a public holiday earns at different rates on either side of midnight
• → Penal rate windows (e.g. time-and-a-half after 10pm on Sundays) have exact start and end times — minute-level accuracy matters
• → Unpaid breaks are deducted at the average rate earned during the shift — not the base rate — which can only be computed after iterating the full shift

Rational Accumulation → Decimal Output

During the loop, each minute's pay contribution is rate / 60 — a division that produces a repeating decimal. If you accumulate those divisions as floating-point doubles, rounding errors compound across hundreds of iterations. Even Dart's Decimal type introduces truncation on division.

The solution is to use Rational — a type that represents exact fractions with no precision loss — for the entire accumulation phase, then convert to Decimal only at the very end.

// Each minute is processed independently
Rational totalValue = Rational.zero;
DateTime cursor = startTime;

while (cursor.isBefore(endTime)) {
  // Resolve rate for this exact minute (holiday? penal rate window?)
  final rate = _resolveRate(cursor, baseRate, multipliers, isHoliday);

  // Accumulate as exact fraction — no rounding during the loop
  totalValue += Rational.parse(rate.toString()) / Rational.fromInt(60);
  cursor = cursor.add(const Duration(minutes: 1));
}

// Decimal conversion happens once, at the end
final gross = Decimal.parse(totalValue.toDecimal(scaleOnInfinitePrecision: 10).toString());
final breakCost = unpaidBreak * (gross / totalHours);
final grossPay = gross - breakCost;

String Storage in SQLite

SQLite has no native decimal type. Storing financial values as REAL (float) introduces IEEE 754 rounding the moment the value hits the database. ShiftPay stores every financial figure as a TEXT column — the exact string representation of the Decimal — and parses it back on read. The value that goes in is exactly the value that comes out.

The Snapshot Pattern

When a shift is saved, the current hourly rate and tax code are captured alongside the calculated figures. This means every shift record is a self-contained audit document. If a user changes their hourly rate or tax code in settings later, past shifts are unaffected — they reflect exactly what was earned at the time they were logged. This is the foundation of ShiftPay's payslip verification capability.

Public Holiday Detection with Mondayisation

NZ public holidays that fall on a weekend are "Mondayised" — observed on the following Monday. The engine hardcodes NZ national holidays for the current year, then applies the Mondayisation rules programmatically. A nurse starting a shift at 11:30pm on ANZAC Sunday earns at 1.5x from midnight, not from the start of their shift — and the minute-by-minute loop captures that transition exactly.