PayrollEngine
Open-source framework for regulation-driven payroll applications — multi-tenant, multi-country, API-first, with No-Code/Low-Code automation and test-driven development.
Install / Use
/learn @Payroll-Engine/PayrollEngineREADME
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.
What is the Payroll Engine?
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.
Why Payroll Engine?
| | 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 |
Who Is This For?
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 ↗.
How It Works
┌──────────────────────────────────────────────────────────┐
│ 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 ↗.
Prerequisites
| 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) |
Quick Start
The Payroll Engine runs as a Docker container stack. Docker is the only prerequisite for the hosted setup.
1. Login to the GitHub Container Registry:
Create a GitHub Personal Access Token with the read:packages scope, then login:
echo "<your-pat>" | docker login ghcr.io -u <github-username> --password-stdin
This is a one-time step per machine.
2. Clone the repository and create the environment file:
git clone https://github.com/Payroll-Engine/PayrollEngine.git
cd PayrollEngine
echo "DB_PASSWORD=PayrollStrongPass789" > .env
# Windows (PowerShell)
git clone https://github.com/Payroll-Engine/PayrollEngine.git
Set-Location PayrollEngine
"DB_PASSWORD=PayrollStrongPass789" | Out-File .env -Encoding utf8
Use alphanumeric characters only for the password — special characters can cause misleading authentication errors.
3. Start the stack:
docker compose -f docker-compose.ghcr.yml up -d
4. 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.
Docker Images
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:latest
Pin a specific version by replacing :latest with the release tag (e.g. :2.1.0).
.NET Integration
Add the Client SDK to integrate the Payroll Engine into any .NET application:
dotnet add package PayrollEngine.Client.Services
Connect 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 integrati
Related Skills
node-connect
351.8kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
prose
351.8kOpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
frontend-design
110.9kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
351.8kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
