← 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