Content moderation workflow
User reports, automated checks, review queue, and enforcement.
Content moderation at any scale requires a pipeline: some violations are obvious and can be caught by automation, others need human eyes, and a few need a specialist to call. This template traces a report from submission through automated checks, the human review queue, escalation, and final enforcement — with clear exit states for approved and rejected content.
The state machine format shows you the decision points and the states where work pauses (UnderReview, Escalation). Team members can see at a glance what state a report is in and who needs to act next.
When to use this template
- Designing moderation policy — walk through a concrete report: what does automation catch immediately? What needs human eyes? When do you escalate? This diagram is the policy made concrete.
- Onboarding moderators — show the flow so new team members understand the queue they're pulling from and where their decision feeds back.
- Compliance audits — regulators want to see your process. This diagram is auditable evidence that you're not just reactive; you have tiers of review and escalation.
How to adapt it
Tailor the automation and escalation logic to your needs:
- Add severity-based routing — high-severity content (threats, hate speech) skip Queued and go straight to EscalationQueue. Low-severity (minor spam) auto-approve after 24h with no moderator action.
- Insert parallel review tracks — if you have multiple content types (text, images, video), spawn separate state machines for each type with different AutoCheck and escalation paths.
- Add an appeal state — from Rejected, add a loop back to UnderReview as "Appeal" with a flag set so the re-reviewer knows context.
Because visual edits regenerate code, you can drag states around, add branches, and rename them to match your exact policy — the result stays syntactically clean.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
stateDiagram-v2
[*] --> Submitted: User reports content
Submitted --> AutoCheck: System processes
AutoCheck --> Queued: Passed filters
AutoCheck --> Removed: Flagged automatic
AutoCheck --> EscalationQueue: High confidence
Queued --> UnderReview: Moderator claims
UnderReview --> Approved: Meets policy
UnderReview --> Rejected: Violates policy
UnderReview --> NeedsEscalation: Ambiguous
EscalationQueue --> Escalation: Senior review
Escalation --> Approved: Clear to publish
Escalation --> Rejected: Violates policy
NeedsEscalation --> Escalation
Approved --> [*]: Content restored
Rejected --> [*]: Content removed
Removed --> [*]: Automatic removal
Frequently asked questions
- Why do moderation workflows need automation before human review?
- Automated checks filter out clear-cut violations (spam, illegal content, known-bad hashes) before your moderation team sees them. This lets your team focus on edge cases and policy gray areas where human judgment matters. Automation also reduces the time between report and action.
- What is an escalation queue?
- An escalation queue collects content that the automated system flagged with high confidence but wants a human to confirm before removal. It also collects ambiguous cases where the moderator can't decide — they go to a senior or specialist reviewer for a final call. This creates a middle ground between instant automation and full human review.
- How do I handle appeals?
- After rejection, most policies allow users to appeal — that's a new flow that loops back into the moderation queue with the user's appeal context attached. The moderator re-reviews with fresh perspective. You can add an 'Appeal' branch from the Rejected state that loops back to UnderReview with a flag set.
- Can I extend this for multiple content types or severity levels?
- Yes. Add entry states before Submitted (e.g., Image, Text, Video) that route to different AutoCheck logic, or add severity branches (Minor → Queued, Major → EscalationQueue directly). Visual edits regenerate clean Mermaid code, so you can grow the workflow as your policy becomes more nuanced.
Related templates
Multi-step approval workflow
Submission, review, approval, rejection, and completion states.
Data retention and compliance
State machine for customer data lifecycle under GDPR and privacy laws.
Subscription lifecycle state machine
Plan upgrades, downgrades, cancellation, and grace period recovery.