Payroll Operations Documentation
Summary
Complete source-backed operations documentation for Payroll, including confirmed implementation, Transitional boundaries, unsupported capabilities, and safe operating guidance.
Audience
Payroll users, developers, QA and support engineers, architects, product owners, and implementation reviewers.
Overview
Scope and operating posture
This section covers the confirmed Payroll runtime, configuration categories, startup order, hosted projection consumer, health and telemetry, calculation lifecycle, projection synchronization, outbox state, payslip and export handling, cutover/rollback evidence, smoke testing, support, and escalation. It deliberately omits environment values, infrastructure topology, credentials, and copy-paste operational commands.
Payroll is Transitional: native and compatibility request paths share Payroll persistence while lifecycle and error semantics can differ. Operators must identify the path in use before interpreting a status or attempting recovery. Foundation capabilities are usable building blocks but are not evidence of end-to-end automation. Items marked Requires confirmation need owner evidence before production reliance; Not implemented means the reviewed source contains no such capability.
Runtime control map
| Concern | Confirmed behavior | Operational classification |
|---|---|---|
| HTTP runtime | Payroll endpoints, compatibility endpoints, persistence, authentication/context middleware, and OpenAPI/health wiring are registered | Transitional |
| Hosted work | PayrollReadModelConsumer synchronizes upstream Employee, Attendance, Leave, and Expense events | Foundation |
| Calculation | Native calculation reads Payroll-owned projections; compatibility calculation/save behavior also exists | Transitional |
| Freeze/unfreeze | Reversible lifecycle operations; native and compatibility unfreeze statuses differ | Transitional |
| Payslip and bank output | Native output requires frozen data; compatibility payslip/PDF behavior also exists | Transitional |
| Outbox | Event intent is persisted with Payroll changes | Foundation; relay ownership Requires confirmation |
| Health | Shallow service health endpoint | Foundation; dependency readiness Not implemented |
| Telemetry | Shared structured logging and tracing registration | Foundation; Payroll-specific metrics Not implemented |
| Caching | No Payroll-specific cache confirmed | Not implemented |
| Payment/accounting | No execution, acknowledgement, reconciliation, or ledger posting | Not implemented |
Safe operating principles
- Correlate by tenant, period, run, employee reference, request correlation, and event identifier; do not place employee or compensation data in tickets.
- Inspect before mutating. A retry is safe only after confirming the previous request did not commit.
- Never edit Payroll or projection tables as a recovery shortcut.
- Treat freeze as reversible locking, not payment, posting, approval, or irreversible finalization.
- Validate projection freshness before calculation and outbox disposition after state-changing operations.
- Stop and escalate when ownership, tenant context, lifecycle path, or delivery outcome cannot be proved.
Documentation map
- Payroll Runtime Operations
- Payroll Configuration and Startup
- Payroll Health and Observability
- Payroll Calculation and Lifecycle Operations
- Payroll Projection Synchronization Operations
- Payroll Outbox Operations
- Payroll Payslip and Export Operations
- Payroll Cutover and Rollback Operations
- Payroll Smoke and Scenario Testing
- Payroll Support, Escalation, and Operational Checklist
Operational entry points
Use runtime operations and configuration/startup for service readiness. Use calculation and lifecycle operations, projection synchronization, outbox operations, and output operations during Payroll processing. Release and support teams should use cutover/rollback, smoke testing, and the support checklist.
Source References
microservices/src/payroll-service/Program.csmicroservices/src/shared-kernel/Extensions/ObservabilityExtensions.csmicroservices/src/payroll-service/Infrastructure/PayrollDbContext.csmicroservices/src/payroll-service/Infrastructure/Persistence.csmicroservices/src/payroll-service/Application/PayrollCalculationService.csmicroservices/src/payroll-service/Application/PayrollCompatService.csmicroservices/src/payroll-service/Messaging/PayrollReadModelConsumer.csmicroservices/src/contracts/Events/PayrollCalculatedEvent.csmicroservices/src/contracts/Events/PayslipGeneratedEvent.csmicroservices/src/payroll-service/Application/PayrollOutputsService.csmicroservices/docs/payroll-cutover-runbook.mdmicroservices/scripts/compare-payroll-parity.ps1microservices/scripts/payroll-cutover-go-no-go.ps1microservices/scripts/smoke-payroll-cutover.ps1microservices/scripts/smoke-payroll.ps1scripts/validate-payroll-scenarios.ps1
Related Articles
See Also
Keywords
- Payroll operations
- Payroll module
Revision Information
- Status: Draft
- Last reviewed: 2026-07-15
- Review cycle: Quarterly