Task Queue State Diagram
The code
stateDiagram-v2
[*] --> Queued: enqueue
Queued --> Running: worker claims
Running --> Queued: retry later
Running --> Done: success
Running --> Failed: error
Failed --> Queued: backoff
Failed --> Dead: retries exhausted
Done --> [*]
Dead --> [*]: alert
How this template works
Background jobs live and die by their retry policy, and this diagram makes the policy visible. A job is enqueued into Queued, claimed by a worker into Running, and then exits three ways: success, failure with a retry, or failure that exhausts its attempts. The Failed state is not a dead end — it feeds either back into Queued after backoff or forward into Dead, the dead-letter state where a human gets involved.
The syntax shows off loops and multiple exits. Running --> Queued: retry later and Failed --> Queued: backoff are the two edges that point backwards, and drawing them explicitly is what separates a real queue design from a happy-path sketch. A single state can have several outgoing transitions — Running has three here — and the labels after the colons name the events that choose between them. Two states reach the [*] end marker: Done silently, and Dead with an alert label, which documents that termination of a dead job is an operational event, not just cleanup.
The gotcha is unbounded loops. The pair of retry edges here is safe only because the Failed state has a second exit; if you delete the retries exhausted transition, the diagram describes a job that can fail forever. When you adapt the file, count the ways out of every looping state before you render it. Also keep the label text short — the labels sit on the arrows, and long sentences there make the layout sprawl.
To tailor it, add a Scheduled state before Queued for jobs with a future run time, or add a manual replay edge from Dead back to Queued for ops tooling. Rename Done to Succeeded if that matches your worker library.
Related templates for other operational flows: the order lifecycle state diagram for business entities, the auth session state diagram for session handling, and the subscription billing state diagram for payment retries. The state diagram guide is the syntax reference.
Variations to try
- Add a Scheduled state before Queued for jobs that can be enqueued with a future run time.
- Add a transition from Dead back to Queued labeled manual replay for ops tooling.
- Rename Done to Succeeded if that is the vocabulary your worker library uses.
