← All Diagrams
Policy Lifecycle State Machine
state diagram
Policy workflow from draft creation through approval, publishing, template update acceptance, expiry, and renewal — including all API endpoints and self-approval guard.
Source: policy-state-machine.mmd
stateDiagram-v2
[*] --> draft : Manager/Admin creates policy\nvia two-step wizard:\n1 — Template Picker (recommended or fallback browse)\n2 — Policy Form (pre-filled from template or blank)\nPOST /api/policies\n[sourceTemplateId + sections[] stored if template used]
draft --> pending_approval : Manager submits for review\nPOST /api/policies/{id}/submit\n[or POST /api/policies/{id}/approval-request]\n→ notifies all admins + owner; starts the approval clock
pending_approval --> draft : Admin/Owner rejects\nPOST /api/policies/{id}/approve {action:"reject"}\n→ notifies creator with rejection reason
pending_approval --> approved : Admin/Owner approves\nPOST /api/policies/{id}/approve {action:"approve"}\n[author can't self-approve while another active admin exists (403)]\n[only owners left → override with reason (409 → override) → audit + owner notified]\n[author is the only admin/owner → waived, audit-logged]
approved --> published : Admin publishes\nPOST /api/policies/{id}/publish\n→ notifies all scoped employees
published --> expiring : Cron job detects\nexpirationDate ≤ 30 days away
expiring --> expired : Cron job detects\nexpirationDate passed
expired --> pending_approval : Admin renews (content changed)\nPOST /api/policies/{id}/renew {contentChanged:true}\n→ requires re-approval before republishing
expiring --> published : Admin renews (dates only)\nPOST /api/policies/{id}/renew {contentChanged:false}
draft --> [*] : Admin hard-deletes draft\nDELETE /api/policies/{id}
note right of draft
Template linkage (set at creation):
• sourceTemplateId — master template ID
• sourceVersion — version adopted
• sections[] — structured content blocks
Populated by GET /api/policies/templates/:id
(tenant-accessible, published templates only)
Template update flow (post-publish):
templateUpdateAvailable → banner shown
↓ accept: merge template sections
POST /api/policies/{id}/accept-template-update
↓ dismiss: clear flag
POST /api/policies/{id}/dismiss-template-update
end note
note right of pending_approval
Approval thread:
GET /api/policies/{id}/approval-request
POST /api/policies/{id}/approval-request/comment
Comments visible to creator + reviewers
Escalation (#61, worker job POLICY_APPROVAL_ESCALATION,
weekdays 9am tenant time, business days):
• 5 days pending → in-app reminder to admins/owners (not the author)
• 10 days pending → owner(s) escalated: in-app + email
Each fires once per round; resubmitting restarts the clock
(submittedForApprovalAt / approvalReminderSentAt / approvalEscalatedAt)
end note
note right of published
Acknowledgment:
POST /api/policies/{id}/acknowledge
Tracks per-user annual sign-off
needsAcknowledgment flag on GET /api/policies/{id}
end note