Configurable HR & Payroll Engines

Most software is forgiving. A bug in your task management app means someone's todo item is in the wrong column. A bug in your payroll engine means an employee receives the wrong net pay, you file incorrect tax withholdings, or your direct deposit file is rejected by the ACH processor. Any of these is a crisis with immediate, concrete consequences.

This is why payroll software is hard to build well, and why it's hard to find engineers who've actually done it before. The mathematical requirements are strict. The regulatory requirements are jurisdiction-specific and change regularly. The formatting requirements for bank clearance files are meticulous. And the audit requirements mean every calculation must be reconstructable from its inputs, even years later.

The Configurable HR & Payroll Engine is a payroll calculation and disbursement core designed to be embedded inside HR software platforms. It solves the math problem correctly, handles the regulatory edge cases, and generates the outputs that downstream systems (banks, tax authorities, accounting software) actually need.

The Mathematics of Payroll Done Correctly

JavaScript's native floating-point arithmetic is not safe for financial calculations. 0.1 + 0.2 in JavaScript evaluates to 0.30000000000000004. When that error propagates through hundreds of calculation steps across thousands of employee records, you don't get a rounding error — you get incorrect pay stubs and potential legal exposure.

This engine uses MathJS with arbitrary-precision arithmetic for all monetary calculations. Every amount is represented as a Decimal type, not a floating-point number. Addition, multiplication, division, and rounding all use explicit precision rules that match the requirements of the calculation context.

The calculation pipeline processes deductions in the legally mandated sequence:

1. Gross wages (base salary, overtime, bonuses, commissions — all calculated separately)
2. Pre-tax deductions (401k, HSA, FSA contributions — reduce taxable income)
3. Federal income tax withholding (W-4 allowances, filing status, bracket calculation)
4. State income tax (multi-state support, residency vs. work location rules)
5. FICA taxes (Social Security wage base cap tracking, Medicare surcharge)
6. Post-tax deductions (Roth IRA, garnishments, voluntary benefits)
7. Net pay

Each step is logged with inputs, applied rates, and outputs. If an employee questions their pay stub, you can trace the exact calculation that produced each line item.

Tax Logic That Covers Real-World Complexity

The basic case — single state, salaried employee, standard W-4 — is not the hard part. The hard part is the edge cases that your enterprise clients will bring to you:

Multi-state employees: Remote workers who live in one state and work (or are legally employed) in another trigger reciprocity agreements, credit for taxes paid to another state, and sometimes nexus in states where you'd rather not have it.

Supplemental wages: Bonuses, commissions, and severance are taxed differently from regular wages — the IRS allows (and sometimes requires) a flat 22% federal withholding on supplemental wages rather than the regular withholding calculation.

Social Security wage base: Social Security tax stops being withheld once an employee's cumulative earnings exceed the annual wage base ($168,600 in 2024). The system tracks this per employee and stops withholding automatically.

Medicare surcharge: The additional 0.9% Medicare tax kicks in for high earners. Employers aren't required to know about all sources of income, which creates an employee-side obligation — but your payroll system needs to track this correctly for the W-2.

Garnishments: Wage garnishments (child support, student loans, IRS levies, creditor judgments) have specific legal priority ordering and maximum withholding limits. The engine supports multiple simultaneous garnishments with correct sequencing.

NACHA File Generation for Direct Deposit

The last step in payroll is getting the money into employee bank accounts. The ACH (Automated Clearing House) network has a specific file format — NACHA — that banks and payroll processors require. This format is notoriously particular: fixed-width fields, specific record types, hash totals, and blocking factors that must be calculated exactly.

The engine generates valid NACHA files that can be submitted directly to your bank or ACH processor. The format is tested against the NACHA standard and has been accepted by major US banks. Batch support allows combining multiple companies' payrolls into a single submission file where required.

Immutable Audit Trail

Every calculation run is stored with its complete inputs and outputs. This isn't just a log — it's a versioned record that allows exact reconstruction of a historical payroll run even if tax rates or employee records have changed since.

Regulatory audits, employee disputes, and amended tax filings all require the ability to say "here is exactly what was calculated, with these inputs, on this date, by this user." The audit log covers that completely.

Access to modify payroll records and run calculations is governed by role-based permissions. The audit log itself is append-only and cannot be modified even by system administrators.