Designing a Payroll System in Rails: Idempotency, Audits, and Compliance
Payroll is the least forgiving software you will ever build. Here is how I approach it in Ruby on Rails: immutable ledgers, idempotent runs, complete audit trails, and automated compliance reporting.
Payroll software is unforgiving in a way that most web applications are not. A bug does not just annoy a user; it can underpay a family or trigger a tax filing error. I have built a modern payroll system in Rails that cut processing time and errors, and the lessons generalise to any system that moves money.
Model the money as an immutable ledger
Never store a balance as a mutable column that you increment and decrement. Store transactions, and derive balances. An append-only ledger gives you a complete history, makes corrections explicit instead of destructive, and lets you reconstruct the state of the system at any point in time.
CREATE TABLE ledger_entries (
id BIGSERIAL PRIMARY KEY,
run_id BIGINT NOT NULL,
employee_id BIGINT NOT NULL,
kind TEXT NOT NULL,
amount_cents BIGINT NOT NULL,
currency TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (run_id, employee_id, kind)
);
That UNIQUE constraint is doing real work. It is the database-level guarantee that a repeated run cannot post the same entry twice.
Idempotency is a requirement, not a feature
Jobs retry. Webhooks arrive twice. Network timeouts leave you unsure whether the write happened. In payroll, every one of these is a double-payment waiting to occur. The answer is an idempotency key for every state-changing operation, enforced by a uniqueness constraint in the database.
- Derive the key deterministically: run, employee, and pay component.
- Enforce uniqueness in Postgres, not only in application code.
- Make the operation safe to run twice and identical the second time.
- Record the outcome of every attempt, including the no-op ones.
Test the retry path, not just the happy path
Run your payroll suite with every job executed twice. If any test fails, you have found a double-payment bug in development rather than in production.
Audit everything, including who read it
Compliance is not decoration; it is a core requirement of the domain. Every change to a pay component, every approval, and every export must be attributable to a user at a specific time. For sensitive data, log reads as well as writes.
- Use a paper-trail style versioned audit table for every financial model.
- Capture the actor, the before and after values, and the reason for the change.
- Make audit records append-only and immutable to the application.
- Retain records according to the jurisdictions you operate in.
Compliance reporting should be generated, not assembled
Manual reporting is where errors live. Tax filings, pay stubs, and regulatory exports should be generated deterministically from the ledger, with the same idempotency guarantees as the payments themselves. A report you generate twice should be byte-identical.
Segregate permissions aggressively
The person who defines a pay rate should not be the only person who approves it. Model roles explicitly — preparer, approver, auditor — and enforce separation of duties in code, not in a policy document. Use a real authorisation library, keep permissions in the database, and test the negative cases.
authorize! :approve, payroll_run
raise "separation of duties" if payroll_run.prepared_by == current_user
Make changes reversible, not editable
A correction should be a new, compensating entry with a reference to the original, never an in-place edit. This preserves the audit trail, makes the correction reviewable, and keeps the ledger internally consistent.
The discipline payroll forces on you — idempotency, immutability, and auditability — is exactly the discipline that makes every other backend you build more reliable.
Build the ledger, enforce idempotency in the database, audit everything, generate reports deterministically, and separate duties. The result is a payroll system that is boring in the best possible way: it runs, it reconciles, and it can prove what it did.