Skip to main content

Payroll Technical Documentation

Summary​

This section describes the source-confirmed architecture and technical boundaries of Payroll Service without duplicating API, database, event-contract, UI, operations, or troubleshooting reference material.

Audience​

Backend and frontend developers, QA and DevOps engineers, support and security engineers, solution architects, and engineers onboarding to Payroll.

Overview​

Technical scope​

Payroll Service is a .NET 8 ASP.NET Core service for Payroll-owned periods, runs, workforce/input projections, calculation, reversible freeze, outputs, audit/timeline evidence, and integration events. It uses minimal APIs, direct scoped services, EF Core/PostgreSQL, a broker consumer, and Shared Kernel observability/messaging foundations.

Runtime responsibilities and dependencies​

The service owns Payroll computation and records. It consumes Employee, Attendance, Leave, and Expense facts; maintains local advance-recovery state; generates payslip/PDF/CSV outputs; and publishes Payroll events through outbox records. Conceptual runtime dependencies are the gateway, PostgreSQL, integration broker, upstream event producers, Shared Kernel/Contracts, and Notification consumers.

Current maturity​

Transitional. Native and compatibility surfaces coexist behind gateway-controlled cutover. Input backfill and parity tooling exist. Automatic outbound relay, service-local authorization, dependency readiness, Document Service storage, Workflow integration, payment execution, accounting posting, and formal Payroll .NET tests are incomplete or require confirmation.

Technical documentation map​

  1. Payroll Service Architecture
  2. Payroll Service Responsibilities
  3. Payroll Project Structure
  4. Payroll Layered Architecture
  5. Payroll Domain Model
  6. Payroll Run Aggregate
  7. Payroll Period Model
  8. Payroll Workforce Projection
  9. Salary Component Model
  10. Earnings and Deductions Model
  11. Payroll Calculation Engine
  12. Attendance Input Boundary
  13. Leave Input Boundary
  14. Expense Input Boundary
  15. Advance Recovery Boundary
  16. Payroll Application Layer
  17. Payroll Infrastructure Layer
  18. Repository and Unit of Work
  19. Command and Query Flow
  20. Payroll Technical Validation
  21. Freeze and Unfreeze
  22. Payslip Generation
  23. Bank Export Foundation
  24. Payroll Tenant Context
  25. Payroll Gateway Interaction
  26. Messaging and Outbox
  27. Payroll Document Integration
  28. Payroll Notification Integration
  29. Payroll Workflow Boundary
  30. Payroll Dependency Injection
  31. Payroll Configuration
  32. Payroll Security Boundaries
  33. Payroll Observability
  34. Payroll Health Checks
  35. Payroll Performance Considerations
  36. Payroll Testing Architecture
  37. Payroll Known Limitations
  38. Payroll Future Evolution

Source References​

  • microservices/src/payroll-service/Program.cs
  • microservices/src/payroll-service/payroll-service.csproj
  • microservices/src/payroll-service/Application/PayrollCalculationService.cs
  • microservices/src/payroll-service/Application/PayrollOutputsService.cs
  • microservices/src/payroll-service/Infrastructure/PayrollDbContext.cs
  • microservices/src/payroll-service/Messaging/PayrollReadModelConsumer.cs
  • microservices/src/gateway-api/Program.cs

See Also​

Keywords​

  • Payroll Service
  • Payroll Technical Documentation
  • Technical architecture

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly