Payroll cycle status machine
The payroll cycle moves through 16 states from creation to archival. Transitions are enforced by canTransition() in packages/domain/src/payroll/rules/status-transitions.ts.
What each state means
Click to expand
| State | Meaning | Who moves it forward |
|---|---|---|
PLANNED | Cycle created by the platform but not yet sent to the client | Worker (cycle-initiate cron) |
REQUESTED | Cycle request email sent | Worker |
INTAKE_IN_PROGRESS | Client opened the magic link; intake is editable | Client submitter |
SUBMITTED | Client submitted; validation runs | Worker (validation-run) |
ACTION_REQUIRED | Validation produced blocking issues client must fix | Client (after fix) → SUBMITTED |
READY_FOR_INTERNAL_REVIEW | Validation passed; ops review pending | Payroll Executive |
READY_FOR_EXPORT | Internal review passed | Payroll Executive |
EXPORTED | Infotech import workbook generated | Worker → Payroll Executive uploads output |
OUTPUT_IMPORTED | Output workbook uploaded and parsed | Payroll Executive requests approval |
CLIENT_REVIEW | Approval request sent to client approver | Client approver |
CLIENT_QUERY_OPEN | Client opened a query on a line item | Payroll Executive resolves → CLIENT_REVIEW |
APPROVED | Client approver signed off | Payroll Executive finalizes |
REVISION_REQUESTED | Client approver rejected; revision needed | Re-enters INTAKE_IN_PROGRESS for round 2+ |
FINALIZED | All artifacts locked | Payroll Executive (or scheduled) closes |
CLOSED | Cycle complete; available in history | System (after retention window) archives |
ARCHIVED | Cycle moved to cold storage per retention policy | Terminal |
Where these transitions happen in the handbook
Each transition has a corresponding userflow page:
PLANNED → REQUESTED: Initiate (P-01)REQUESTED → INTAKE_IN_PROGRESS → SUBMITTED: Client intake & changes (P-02), Zero-change fast path (P-03)SUBMITTED → ACTION_REQUIRED / READY_FOR_INTERNAL_REVIEW: Validation (P-04)ACTION_REQUIRED → SUBMITTED: Request info from client (P-05)READY_FOR_INTERNAL_REVIEW → READY_FOR_EXPORT: Internal review (P-06)READY_FOR_EXPORT → EXPORTED: Generate Infotech export (P-07)EXPORTED → OUTPUT_IMPORTED: Upload Infotech output (P-08)OUTPUT_IMPORTED → CLIENT_REVIEW: Request client approval (P-09)CLIENT_REVIEW → APPROVED / REVISION_REQUESTED: Client approval response (P-10)APPROVED → FINALIZED → CLOSED: Finalize & close (P-11)