The open-source payroll automation framework.
Build multi-country, multi-industry payroll applications with configurable regulation layers.
Docs · Quick Start · Resources · Releases · Discussions
This repository contains the Docker stack, payroll examples, automated tests, JSON schemas, and release artifacts. Full documentation — concepts, guides, and API reference — is available at payrollengine.org.
The Payroll Engine is a framework for developing payroll applications. It is designed for software companies, payroll service providers, and enterprises that need to automate and scale payroll processing across countries and industries.
The key idea: payroll logic is not hardcoded. Instead, business rules are defined in configurable regulation layers ↗ that can be stacked, overridden, and shared between tenants. This separation of business rules from application code makes the engine adaptable to any country, any industry, and any HR platform.
| Traditional Payroll Software | Payroll Engine | |
|---|---|---|
| Business rules | Hardcoded in source code | Configurable regulation layers |
| Multi-country | Separate codebases or modules | Stackable country regulations |
| Customization | Custom development per client | Override layers per tenant |
| Testing | Manual or integration tests | Built-in test-driven development |
| Deployment | Monolithic or SaaS | Embedded via REST API or Docker |
| Time model | Overwrites existing data | Time-stamped values with full history |
| License | Commercial | MIT — free for any use |
The Payroll Engine serves three distinct roles:
| Role | Description | Primary Interface |
|---|---|---|
| Provider | Software vendors and payroll service providers who host and operate the engine for their clients | REST API |
| Regulator | Payroll domain experts who define and maintain country- or industry-specific calculation rules | No-Code (Actions) · Low-Code (C#) |
| Automator | DevOps and integration engineers who connect the engine to HR platforms, data pipelines, or custom applications | Client Services (.NET SDK) |
If you're a payroll domain expert who wants to define rules without writing application code, start with No-Code & Low-Code Development ↗. If you're a .NET developer integrating the engine into an existing system, start with Client Services ↗.
┌──────────────────────────────────────────────────────────┐
│ Payroll Engine │
│ │
│ Regulations Payrun Results │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Country │ │ │ │ Payslips │ │
│ │ Industry │───▶│ Wage Types │───▶│ Reports │ │
│ │ Company │ │ Collectors │ │ Exports │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ Regulation Cases (Input) │
│ Layers Time Data │
│ │
│ REST API · Client SDK · Docker · Multi-Tenant │
└──────────────────────────────────────────────────────────┘
Regulation layers define what to calculate — cases, wage types, collectors, reports, and lookups. Layers are stacked (base → country → industry → company) and objects from lower layers can be overridden.
Cases capture all wage-relevant data as time-stamped events with validity periods. This enables continuous payroll — run at any time, not just month-end — with unlimited cancel/undo and automatic retrospective calculations.
Payrun processes case data through the wage types and collectors defined in the regulation layers, producing payslips, reports, and data exports.
📖 Read more in the Overview ↗ or explore the Payroll Model ↗.
| Requirement | Version |
|---|---|
| Docker | 20.10+ (for container-based setup) |
| SQL Server | 2019+ or Azure SQL (for source builds) |
| .NET SDK | 8.0+ (for Client Services / source builds) |
The Payroll Engine runs as a Docker container stack. Docker is the only prerequisite for the hosted setup.
1. Create the project directory and environment file:
# Linux / macOS
mkdir payroll-engine && cd payroll-engine
echo "DB_PASSWORD=PayrollStrongPass789" > .env# Windows (PowerShell)
New-Item -ItemType Directory payroll-engine; Set-Location payroll-engine
"DB_PASSWORD=PayrollStrongPass789" | Out-File .env -Encoding utf82. Download and start the stack:
curl -O https://raw.githubusercontent.com/Payroll-Engine/PayrollEngine/main/docker-compose.yml
docker compose up -d3. Access the applications:
| Service | URL |
|---|---|
| Web Application | http://localhost:8081 |
| Backend API | http://localhost:5001 |
The database is initialized automatically on first run. See Container Setup ↗ for the full configuration including version pinning and upgrades.
Pre-built Linux images are published to the GitHub Container Registry:
docker pull ghcr.io/payroll-engine/payrollengine.backend:latest
docker pull ghcr.io/payroll-engine/payrollengine.webapp:latest
docker pull ghcr.io/payroll-engine/payrollengine.payrollconsole:latestPin a specific version by replacing :latest with the release tag (e.g. :2.1.0).
Add the Client SDK to integrate the Payroll Engine into any .NET application:
dotnet add package PayrollEngine.Client.ServicesConnect and query employees in a few lines:
using PayrollEngine.Client.Services;
var httpClient = new HttpClient { BaseAddress = new Uri("http://localhost:5001") };
var tenantService = new TenantService(httpClient);
var tenants = await tenantService.QueryAsync();
foreach (var tenant in tenants)
Console.WriteLine($"Tenant: {tenant.Identifier}");All library packages are available on NuGet.org and GitHub Packages.
See Client Services ↗ and API Usage ↗ for full integration guides.
Payroll Processing — Regulation-based calculation with wage types and collectors. Multiple payruns per period, company divisions, forecasts, and instant payrun preview without side effects.
Multi-Country & Multi-Industry — Stackable regulation layers for any combination of country and industry rules. Multi-tenant with regulation sharing between companies.
Time Data & Continuous Payroll — Every data change is time-stamped with a validity period. Payroll runs are possible at any time. Past changes trigger automatic retrospective calculations; future changes apply when due.
No-Code & Low-Code — Case actions for data-entry control without writing code. C# scripting for custom business rules within an isolated, sandboxed scripting runtime.
Test-Driven Development — Automated testing of input (cases), processing (payrun), and output (reports). Test cases are defined alongside regulations and executed via Payroll Console or CI pipelines.
Embedded & API-First — REST API with Swagger/OpenAPI. .NET Client SDK. Docker containers for Backend, WebApp, and Console. OAuth 2.0 and API key authentication.
📖 Full feature list in the Documentation ↗.
This is the main repository containing setup files, examples, tests, and documentation. The source code is distributed across multiple repositories:
PayrollEngine/ ← You are here
├── docker-compose.yml Docker stack configuration
├── Setup/ Setup and configuration files
├── Examples/ Payroll examples (JSON/YAML)
├── Tests/ Automated payroll tests
├── Schemas/ JSON schemas for exchange format
├── Commands/ Payroll Console command files
└── docs/ API documentation, Swagger
| Repository | Description | |
|---|---|---|
| PayrollEngine | Main repo — setup, examples, tests, docs |  |
| Backend | REST API server + SQL Server persistence |  |
| WebApp | Blazor web application | |
| PayrollConsole | CLI for automation, testing, data import | |
| Client.Services | .NET Client SDK (NuGet entry package) |  |
| Client.Scripting | Scripting API for regulation development |  |
| Client.Core | Client core objects |  |
| Client.Test | Test runner library |  |
| Core | Core payroll objects |  |
| Serilog | Structured logging |  |
| Document | Report generation |  |
See Repositories ↗ for the full map including third-party dependencies.
Install all examples or run all tests using the Payroll Console:
# Install all examples
docker run --rm --network payroll-engine_default \
-e PayrollApiConnection="BaseUrl=http://backend-api:8080; Port=8080;" \
ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
PayrollImport --importFile Examples/Setup.all.pecmd
# Run all tests
docker run --rm --network payroll-engine_default \
-e PayrollApiConnection="BaseUrl=http://backend-api:8080; Port=8080;" \
ghcr.io/payroll-engine/payrollengine.payrollconsole:latest \
PayrollTest --testFile Tests/Test.all.pecmd| Examples | Tests | ||
|---|---|---|---|
| SimplePayroll | Minimal payroll | Payrun | Core payrun test |
| ActionPayroll | Case actions | RetroPayroll | Retrospective payrun |
| DerivedPayroll | Regulation layers | Calendar | Calendar types |
| ReportPayroll | Reporting | ForecastPayroll | Forecast payrun |
| ExtendedPayroll | Extended tutorial | DerivedPayroll | Regulation inheritance |
See Resources ↗ for the complete list of examples, tests, and client tutorials.
| Article | |
|---|---|
| Payroll Software rethought | payrollengine.org ↗ |
| Design of a scalable Payroll Software | payrollengine.org ↗ |
| Test Driven Payroll Software | payrollengine.org ↗ |
| No-Code and Low-Code for Payroll Software | payrollengine.org ↗ · dev.to |
| Travel through Time Data | payrollengine.org ↗ · dev.to |
| High-performance backend scripting for .NET | dev.to |
Contributions are welcome — whether it's bug reports, regulation examples, documentation improvements, or feature discussions.
The project is approaching its v1.0 release. If you'd like to contribute, please read CONTRIBUTING.md and the Code of Conduct first. The best starting points are:
- 💬 Discussions — questions, ideas, feedback
- 🐛 Issues — bug reports and feature requests
- 📖 Documentation and regulation examples are particularly welcome
The Payroll Engine is licensed under the MIT License. All third-party dependencies use MIT or Apache 2.0 licenses.