Skip to content

Overview

This page explains how the system is structured, how data flows through it, and what concepts make it work — architecture, regulations, time data, and deployment.

The Payroll Engine separates payroll business rules from application code by placing them in configurable regulation layers. The backend server provides a REST API that processes payroll data based on these regulations — independent of any specific country, industry, or HR system.

Core Use Cases

The core payroll use cases cover the following areas:

  • Onboarding — Setting up the tenant with divisions, employees and regulation layers
  • Case Management — Capturing and changing company and employee data over time
  • Payrun — Cyclical and non-cyclical calculation of employee wages
  • Reporting — Evaluation and export of payroll data

The following figure shows the payroll objects involved in the core use cases.

Core Use Cases

See Payroll Model for a detailed description of all objects and their relationships.

Architecture

Tenant Structure

The Payroll Engine is a multi-tenant system. Each tenant represents an independent company with its own data:

Tenant → Division → Employee

A tenant contains one or more divisions (organizational units). Employees are assigned to divisions. Each division is linked to a payroll, which defines which regulation layers apply. Calendars can be configured at tenant, division or employee level.

Regulation Layers

Regulations are the core concept of the Payroll Engine. Instead of hardcoding payroll logic, regulations define the data model, calculations and reports in stackable layers:

Regulation Layers

Each layer can override or extend objects from the layers below using inheritance. A payroll object combines multiple layers into a single composed view, with evaluation order controlled by level and priority. Regulations can be shared between tenants.

The layer concept was designed to address one of the two fundamental sources of payroll complexity: data heterogeneity. Every company has different wage types, employment models, and organizational structures. Layers allow each of these concerns to be tailored independently — country rules, industry rules, company additions and client customizations — without one layer affecting another.

See Regulation Design for guidelines on building regulation layers.

Data Flow

Data moves through three stages within a payroll:

  • Cases capture all wage-relevant data — salary, working hours, absences, benefits — as time-stamped events with validity periods. The case model defines the data entry workflow including validation, field dependencies and No-Code actions.
  • Payrun processes the case data through wage types and collectors defined in the regulation layers. Wage types are calculated in numerical order; collectors aggregate the results. The payrun supports multiple stages (e.g. gross, deductions, net) and can integrate external services between stages. See Payrun Model for details.
  • Results and Reports are generated from the payrun output. Reports are defined within regulations, support multilingual templates and can be used for payslips, legal filings or data exchange.

Key Concepts

Continuous Payroll and Time Data

Unlike conventional systems that overwrite existing data, the Payroll Engine records every change as a time-stamped case value with a validity period. This means payroll runs are possible at any time — not just at month-end. Past changes trigger automatic retrospective calculations, and future-dated changes are applied when their period arrives.

The engine supports four time types: Timeless (no time commitment), Moment (point in time), Period (date range) and CalendarPeriod (distributed across the payroll calendar). This approach enables unlimited cancel and undo operations with full audit trail.

Read Travel Through Time Data for an introduction to the time data concept.

Forecasts and Payrun Preview

Forecasts allow business case simulation using real payroll data in an isolated context. Forecast case data is not considered by legally valid payruns, so any number of what-if scenarios can be run without side effects.

Because the PE's time model separates the Evaluation Date from the current date, forecasts calculate directly in the target period — without computing all intermediate periods first. This is a fundamental capability that most payroll systems cannot offer.

Payrun Preview provides instant payroll validation — the calculation runs without persisting results, which is useful for testing regulations during development.

Payroll Automation

The engine provides two levels of customization:

No-Code — Case Actions are predefined functions (comparable to Excel functions) that control data entry and validation without writing code. Examples include value limits, required field logic and conditional visibility.

Low-Code — Scripting uses C# as the scripting syntax to implement custom business rules within regulation objects. Scripts are expressions embedded directly in JSON — no .NET project or compiler toolchain required. They run in a sandboxed environment with access to the full payroll context.

C# was chosen deliberately over a custom domain-specific language. Payroll calculations are built from basic arithmetic operators — there is no mathematical complexity that requires a specialized language. What payroll specialists need is familiar syntax, operator overloading for time-value arithmetic, and IDE support for debugging. C# provides all of this without adding a language to learn.

Read No-Code and Low-Code Development for Payroll Providers for a detailed introduction.

Payroll Testing

Test Driven Development is a first-class concept. The engine supports automated testing of all three payroll phases: input (case data), processing (payrun) and output (report results). Test cases are defined in JSON alongside the regulation and can be executed through the Payroll Console or CI pipeline.

Deployment

The Payroll Engine is distributed as pre-built Docker images on the GitHub Container Registry (ghcr.io):

Image Description
ghcr.io/payroll-engine/payrollengine.backend REST API server
ghcr.io/payroll-engine/payrollengine.webapp Web application with employee self-service
ghcr.io/payroll-engine/payrollengine.payrollconsole CLI for automation, testing and data import

The complete stack — including SQL Server — runs with a single docker compose up -d. Database initialization and schema migrations are handled automatically. See Container Setup for the full configuration.

For programmatic integration, the engine provides a REST API accessible from any platform or language. The Client SDK is a .NET library for Automators who build tooling and automation workflows on top of the REST API. See Technical Integration for communication patterns and API Usage for request examples.

Roles

Role Who Responsibilities Relevant Pages
Provider HR-tech & EOR platforms Integrate via REST API, run payruns, query results, manage multi-tenant setups API Usage, Technical Integration, Container Setup
Regulator Payroll consultants & HR specialists Build regulation layers, define cases, wage types, collectors and reports — No-Code actions and C# scripting syntax, no .NET required Regulations, Regulation Design, No-Code / Low-Code, Testing
Automator DevOps & integration engineers Build pipelines, batch runs and tooling using the .NET Client Services SDK and CLI, deploy and operate the container stack Client Services, Technical Integration, Container Setup

See also