Use case diagrams

TL;DR

Ask your agent

Name the actors and what each one does, say which ones support the system rather than use it, and say which use cases always include another.

Use Plotwork to draw a use case diagram of our online shop. Customers browse the catalogue, manage the cart, and check out; a guest is a kind of customer who can only browse. Checking out always includes paying by card, and applying a coupon extends a checkout. A support agent refunds orders, and the payment provider is a supporting system on the right that takes part in paying and refunds.

Use Plotwork to draw the use cases of our internal admin console. An operator looks up accounts, suspends an account, and reads usage totals; an auditor reads the action log. Every one of those includes signing in with a code. Add a note on suspending that every action writes a row to the action log.

Use Plotwork to draw a use case diagram of mobile banking with two systems, the mobile app and the branch desk. The customer checks the balance, transfers money, and freezes a card in the app, and transfers and freezes include Face ID. A branch teller opens accounts and raises limits, and raising a limit extends a transfer. Core banking and the card network are systems on the right.

Example

This is the online shop from the first prompt. It shows a generalisation between two actors, an include and an extend between use cases, and a supporting system on the right.

PictureSourceOutline

An internal admin tool

Every use case of the admin console includes signing in, so the four includes meet the sign-in case as one line with one arrowhead. A note under the auditor says it reads only, and a note beside the systems is attached to the case it is about by a dotted line.

PictureSourceOutline

A mobile banking app with two systems

Two systems stack down the middle, each in its own frame and tone. The supporting systems stand on the right, and the extend from the branch desk to the app crosses from one frame to the other on its own track.

PictureSourceOutline

The language

A line is one statement. A # starts a comment. Ids are words such as checkout, pay-card or _x, labels are in double quotes, and options are written key=value. The first line is the header.

The header

usecase "Online shop" desc="What customers do with the shop."

Statements

tone= takes neutral, blue, violet, aqua, orange, green, amber, or red, and icon= takes a name from the closed list of icons, such as lucide:user or simple:stripe. A diagram cannot set a color: the theme chooses every color, in light and dark.

Actors and systems

An actor is someone or something outside the systems that takes part in a use case. A person is drawn as a round badge in violet and a system as a square badge in blue, each with its icon and its name under it. Write type=system for an API, a bank, or another system; an actor whose icon comes from a brand or cloud set, such as simple:stripe, is a system unless type= says otherwise.

Primary actors, who use the system, stand on the left. Write side=right on a supporting actor, one the system calls or relies on, so it stands on the right. Each actor stands at the height of the use cases it takes part in, so the association lines cross little.

A system is a frame with its name and icon in the top-left corner, and the use cases it offers are inside its block. A diagram has up to 4 systems, stacked down the middle, and they are one level deep. A use case written outside every block stands below the systems, outside any frame.

Use cases

A use case is a pill that grows to fit its name, and its name wraps to three lines. sub= adds a line under the name, for a detail or a condition. A tone= tints the pill: green for a good outcome, amber for a warning, and red for something that needs care.

Include, extend, and kind-of

Include and extend join two use cases, and a kind-of joins two actors or two use cases; anything else is an error that says what to write. A link between two use cases runs on a track beside the column of use cases, on the side with fewer actors, so it never crosses another use case. Links of one kind that arrive at one use case meet it as one line with one arrowhead. A kind of an actor stands directly below the actor it is a kind of, joined by a short line up the column.

Notes

note <id> "Text" attaches a note to an actor or a use case. A note on an actor is drawn under its name. A note on a use case stands in a column right of the systems, joined to its use case by a dotted line. Two notes on one actor are joined into one.

note checkout "Needs a signed-in customer"

Limits and warnings

Warnings never stop a diagram from being drawn. Errors do.

The header alone is a valid diagram, drawn empty, so a new diagram can start from it. The layout is plain arithmetic, so even a diagram at the limits is laid out in a few milliseconds.

From Mermaid

Mermaid usecase-beta (and usecase, as Mermaid is likely to name it once it leaves beta) converts to a use case diagram. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1usecase-beta2direction LR3actor Customer4actor Support5systemBoundary Storefront6  Browse("Browse catalogue")7  Checkout("Checkout")8end9Customer --> Browse10Customer --> Checkout11Support --> Checkout12Checkout ..> : include Browse

The converter reports the direction it dropped (M202) and the missing title (M214):

1usecase2
3actor Customer "Customer"4actor Support "Support"5
6system Storefront "Storefront" {7  case Browse "Browse catalogue"8  case Checkout "Checkout"9}10
11Customer -- Browse12Customer -- Checkout13Support -- Checkout14Checkout ..> Browse : include

See also