Design a payroll system

Reference Answer

For a full example answer with detailed architecture diagrams and deep dives, see our Design Payment System guide. While the payment guide focuses on transaction processing, many of the same patterns around multi-step workflows, idempotency, ledger design, and ACID guarantees apply directly to payroll computation and disbursement.

Also review the Message Queues and Databases building blocks for background on durable workflow orchestration and transactional financial storage.

Problem Statement

Design a payroll system that can calculate employee salaries, manage tax deductions, process payments, and adapt to different countries with varying tax laws and regulations. Think of products like ADP, Workday, Gusto, or Paychex where HR teams configure employee data and compensation, run payroll on a recurring schedule, review results, approve, and execute payments to employees and tax authorities.

The core challenge blends correctness, compliance, and money movement. Payroll is a multi-stage batch workflow: gather time and compensation data, apply country-specific tax rules, calculate gross-to-net pay, get approval, initiate payments via banking rails, and generate payslips and compliance reports. Every step must be idempotent, auditable, and versioned. Tax rules change over time and vary by jurisdiction, so the system must support effective-dated rule versions that can be reproduced historically. Interviewers test how you model effective-dated data, orchestrate multi-step batch processes, integrate with external payment providers, and maintain a clear audit trail with safe failure recovery.

Key Requirements

Functional

• Employee setup -- users can configure employees with compensation details, tax elections, benefits deductions, and country-specific settings
• Payroll execution -- users can run payroll for a pay period, preview gross-to-net results, and approve before finalizing
• Payment processing -- the system processes payments to employees and remits tax withholdings to authorities, with clear success and failure statuses
• Reporting and compliance -- users can generate payslips, tax forms, and compliance reports, and perform off-cycle runs or adjustments for corrections

Non-Functional

• Scalability -- support thousands of companies with millions of employees, processing payroll runs that may contain hundreds of thousands of calculations in a single batch
• Reliability -- 99.95% uptime for payroll execution; ensure exactly-once semantics for payment disbursements to prevent duplicate or missing payments
• Latency -- payroll preview for a standard company (500 employees) completes within 30 seconds; individual payment status updates within 5 seconds
• Consistency -- strong consistency for payroll calculations and payment state; eventual consistency acceptable for reporting aggregates

What Interviewers Focus On

Based on real interview experiences, these are the areas interviewers probe most deeply:

1. Multi-Stage Payroll Workflow

A payroll run is not a single operation but a pipeline with dependent stages: ingesting time and compensation data, computing gross-to-net, approval, payment initiation, and filing. Interviewers want to see durable orchestration with clear recovery from partial failures.

Hints to consider:

• Model the payroll run as a state machine or saga with explicit stages (draft, computing, review, approved, paying, completed) and compensating actions at each stage
• Use a durable workflow engine (or implement one with Kafka and a state table) that persists progress and resumes from the last completed step after a crash
• Allow re-running the computation stage without side effects (idempotent recalculation) so approvers can request corrections before finalizing
• Track each employee's individual status within the run separately so a single payment failure does not block the entire batch

2. Effective-Dated Tax Rules and Versioning

Tax laws change, and the system must apply the rules that were in effect during the pay period, not the current rules. Interviewers probe whether you can reproduce historical calculations exactly.

Hints to consider:

• Store tax tables and rule configurations with effective date ranges so the system can look up which version applied during any historical pay period
• Pin each payroll run to a specific rule version snapshot at computation time, recording the version in the run metadata for auditability
• Support mid-period rule changes by prorating: apply the old rate for days before the change and the new rate for days after
• Maintain a country-specific rules engine that can be extended without code deployments, using configuration tables or a domain-specific language

3. Idempotent Payment Disbursement

Moving money to employees and tax authorities is the most critical and dangerous step. Interviewers expect explicit idempotency and failure handling for interactions with external banking rails.

Hints to consider:

• Generate a unique payment idempotency key per employee per payroll run (e.g., payroll_run_id + employee_id) and pass it to the payment provider
• Use an outbox pattern: write the payment intent to the database atomically with the payroll state transition, then process outbox entries asynchronously
• Track payment status in a ledger with immutable entries (initiated, succeeded, failed, reversed) rather than updating a mutable status field
• Implement a reconciliation job that compares bank settlement reports against the internal ledger and flags discrepancies for manual review

4. Audit Trail and Compliance

Financial regulators require a complete, reproducible history of every payroll computation and payment. Interviewers assess whether your design supports this.

Hints to consider:

• Store every payroll run as an immutable snapshot: input data, rule versions used, intermediate calculations, and final results
• Record all employee data changes (salary adjustment, tax election change, new benefits) with effective dates and timestamps for who made the change
• Generate compliance reports (W-2, P60, or equivalent) from the immutable run snapshots rather than reconstructing them from current data
• Support audit queries like "show me exactly how this employee's net pay was calculated in March 2025" by replaying the archived computation

Suggested Approach

Step 1: Clarify Requirements

Begin by confirming scope. Ask whether the system needs to support multiple countries or a single jurisdiction. Clarify the expected number of companies and employees. Determine whether the system handles payment rail integration or treats it as an external dependency. Verify whether off-cycle payroll (bonuses, corrections) is required. Ask about the consistency model: can employees see a pending status briefly, or must payment confirmation be synchronous? Establish whether the focus is on the computation engine, the payment flow, or the full end-to-end system.

Step 2: High-Level Architecture

Sketch the core components: an Employee Service that manages employee profiles, compensation, and tax elections in PostgreSQL with effective-dated records; a Payroll Engine that computes gross-to-net calculations using versioned tax rule configurations; a Workflow Orchestrator that manages the multi-stage payroll run lifecycle; a Payment Service that integrates with external banking APIs using the outbox pattern; a Ledger Service that maintains an immutable record of all financial transactions; and a Reporting Service that generates payslips and compliance documents from run snapshots. Use Kafka as the event backbone for workflow transitions, payment status updates, and downstream notifications.

Step 3: Deep Dive on Payroll Computation and Approval

Step 4: Address Secondary Concerns

Cover payment processing: the Payment Service reads from the outbox, calls the banking API with an idempotency key, records the result in the ledger, and updates the employee's payment status. Discuss reconciliation: a daily job compares bank settlement files against the internal ledger and flags mismatches. Address multi-country support: abstract the tax calculation behind a country-specific rules engine interface so adding a new jurisdiction requires only new configuration, not new code paths. Cover monitoring: track payroll run duration, computation failures per employee, payment success rates, and reconciliation discrepancy counts. Mention disaster recovery: replicate the database synchronously, archive run snapshots to object storage, and ensure Kafka retains events for replay. Touch on scaling: partition payroll computation by company, run large companies in parallel batches, and use Redis for caching frequently accessed tax tables and exchange rates.

Related Learning

• Payment System -- ledger design, idempotent payment processing, and saga patterns
• Job Scheduler -- durable workflow orchestration for multi-stage batch processes
• Message Queues -- Kafka for workflow events, outbox processing, and payment status propagation
• Databases -- PostgreSQL for effective-dated employee records and immutable payroll snapshots
• Caching -- Redis for tax table caching and computation acceleration

Walk through a payroll run for a 500-employee company. The HR admin triggers a run for the current pay period. The Workflow Orchestrator creates a run record in "draft" state, gathers employee data and time records, and transitions to "computing." The Payroll Engine fetches the applicable tax rule version for the pay period, iterates over employees, and for each calculates: gross pay from salary and hours, federal and state tax withholdings using the effective-dated tax tables, benefits deductions, and net pay. Results are stored as an immutable computation snapshot linked to the run. The run transitions to "review" and the admin previews the results. If adjustments are needed, the admin can modify inputs and re-trigger computation (idempotent). On approval, the run transitions to "approved" and payment processing begins. The Workflow Orchestrator emits per-employee payment tasks to the Payment Service. Discuss how individual employee failures are handled: the employee is marked as failed, the rest proceed, and a retry mechanism allows reprocessing failed payments without re-running the entire batch.