Drawing UML use case diagrams

12 min read · last reviewed 2026-10-17

Open in the interactive app: practice, quiz, mock interview →

In one minute

A use case diagram draws a system boundary, the actors outside it (people, roles or other systems), and the goals each actor can achieve through the system. It says who can do what, never how or in what order.
Actors are roles, not people. One person can be a Patient on Monday and a Clinician on Tuesday; an external system such as an insurer's eligibility API is an actor too.
<<include>> means the base use case always performs another one (booking always verifies insurance). <<extend>> means an optional behaviour may hook into the base at a named extension point (cancelling may charge a late fee).
The diagram is the first draft of three real artefacts: the API surface (each use case becomes one or more endpoints or commands), the permission model (each actor becomes a role or scope), and the acceptance test list.
Its value comes from keeping those three in step. A use case with no endpoint is unbuilt, an endpoint with no use case is unowned, and a role holding a permission no use case needs is a security finding.

How it works

The four elements

A telehealth clinic is building a booking platform. Its use case diagram has four kinds of things.

The system boundary is a rectangle named for the system ("Clinic Platform"). Inside is what the team builds; outside is what it talks to. Drawing it forces the first scope argument: is payments inside, or is the payment provider an actor?

Actors stand outside the boundary: stick figures for humans, boxes marked <<system>> for machines. The clinic has Patient, Clinician, Front Desk and Billing Admin, plus the Insurer's eligibility service as a secondary actor that the system calls but that never starts anything.

Use cases are ovals inside the boundary, each a verb phrase for a goal the actor would recognise: Book appointment, Write prescription. "Save row" is not a use case; nobody opens the app wanting to save a row. Associations are plain lines joining an actor to its use cases.

Include, extend and generalization

Three relationships connect elements to each other, and they are the part most teams get wrong.

<<include>> is a dashed arrow from the base to the included use case. Book appointment includes Verify insurance: every booking verifies. Inclusion factors out shared behaviour the way a function does, and Verify insurance needs no actor of its own.

<<extend>> is a dashed arrow from the optional extension to the base, the opposite direction. Apply late fee extends Cancel appointment at an extension point called "within 24 hours of the visit". The base is complete without the extension and does not know it exists, which is the open-closed principle drawn as a picture.

Generalization (solid line, hollow triangle) works on actors and use cases. Billing Admin specializes Front Desk: it can do everything Front Desk can, plus issue refunds. Specialized actors inherit their parent's associations, the same way a subclass inherits methods.

A good rule for spotting misuse: if you would describe the relationship with "sometimes" or "if", it is extend; with "always", it is include; with "first X, then Y", it does not belong on this diagram at all. Sequencing goes on an activity or sequence diagram.

The text behind each oval

Every oval should point at a short written specification: goal, primary actor, preconditions, the main success scenario as numbered steps, extensions (what happens when step 3 fails), and postconditions, as in Alistair Cockburn's template. The diagram is the index and the text is the content; teams that keep only the diagram lose the failure cases, where most design work lives.

Drawing it in Mermaid

Mermaid has no use case diagram type, so a flowchart stands in: a subgraph for the boundary, stadium nodes (["..."]) for use cases, and labelled dotted edges for include and extend. PlantUML supports the notation directly with actor, usecase and rectangle.

Reviewing agent-written diagrams

Agents make the human mistakes faster: CRUD ovals that mirror tables, extend arrows pointing the wrong way, and actors from the org chart ("Manager") that match no role in the identity provider. Ask for the matrix the diagram implies (actor, use case, endpoint, permission) and check it against the code, which the practice task automates.

The same shape elsewhere

A use case diagram is a coverage claim, the trust but verify shape. An auditor mapping controls to evidence and a gateway route table compared with the OpenAPI spec are the same check: two lists written by different people must agree, and gaps in either direction are the findings.

Down the stack

Layer 1The contract

The diagram makes three testable promises. A principal holding an associated actor's role can complete the use case end to end, inclusions included. Included use cases run whenever the base does, so the base actor needs whatever they need. And an actor with no line to a use case cannot perform it; that negative promise is the one auditors test. Nothing is promised about ordering, timing or data.

Layer 2The mechanism

Actors become principals and roles: a scope or roles claim in an OAuth 2.0 JWT, a Kubernetes Role and RoleBinding, an AWS IAM role. Actor generalization becomes role inheritance.

Use cases become entry points: REST routes, gRPC methods, GraphQL mutations or queue consumers. Mature teams record the link, for example with an OpenAPI x-use-case extension, so tooling can join the two.

Include becomes an internal call on the same request path, and its permission propagates up: if POST /appointments calls the eligibility service with the caller's token, that token needs the eligibility scope. Extend becomes a conditional hook (a feature flag, a policy rule, a handler for AppointmentCancelled) the base never references. The boundary becomes the authorization perimeter, usually a gateway or mesh.

Tooling does the drawing. PlantUML parses its text into an element graph and hands use case and class diagrams to Graphviz's dot. Mermaid parses flowchart text with a Jison-generated grammar into a graph of nodes, edges and subgraphs, then lays it out with dagre by default (ELK is an option). Both layout engines use the layered method from Sugiyama and colleagues: break cycles, assign each node a rank, order nodes within ranks to reduce edge crossings, then assign coordinates.

Layer 3The machine

Each association costs something on every request. A scope check on a validated JWT is a set lookup costing well under a microsecond, but validating the token costs more: an RS256 signature check is roughly tens of microseconds on a modern core, which is why gateways cache validated tokens by hash. Scope strings ride in a header on every call. A role model with one scope per use case and 60 use cases adds over a kilobyte to the token, base64 adds a third more, and nginx's default large_client_header_buffers 4 8k rejects any single header line above 8 KB with a 400. Calling an external policy engine such as OPA over the network adds a millisecond or so per decision; embedding it keeps decisions in the tens of microseconds.

Layout has its own limit. Minimising edge crossings in a layered drawing is NP-hard, so engines sweep barycenter or median heuristics. With a few hundred edges the result becomes unreadable long before it becomes slow: split the diagram by actor or subsystem.

Why it's built this way

Stakeholders argue about scope and access long before anyone argues about classes, so the first diagram models goals and roles, not structure.
Roles change less often than people, so actors are roles, and they map directly onto the role or scope model enforced at runtime.
Shared behaviour would otherwise be repeated in every use case text, so include factors it out, and its permissions propagate to every caller.
Optional behaviour added later should not force edits to the base, so extend points from the extension to the base.
Hand-maintained lists drift, so the diagram, the route table and the role grants are joined into one checked matrix.

Diagram

flowchart LR
  P["Patient"]
  F["Front Desk"]
  B["Billing Admin"]
  C["Clinician"]
  I["Insurer (system)"]
  subgraph S["Clinic Platform"]
    U1(["Book appointment"])
    U2(["Verify insurance"])
    U3(["Cancel appointment"])
    U4(["Apply late fee"])
    U5(["Write prescription"])
    U6(["Issue refund"])
  end
  P --- U1
  P --- U3
  F --- U1
  F --- U3
  B -- "specializes" --> F
  B --- U6
  C --- U5
  U1 -. "include" .-> U2
  U4 -. "extend" .-> U3
  U2 --- I

Worked example

The clinic's first release has 9 use cases, 14 endpoints and 5 roles. For the security review an engineer joins three files: the use case list, the OpenAPI spec (each operation tagged with x-use-case and a scope), and the identity provider's role export. The join finds four problems:

GET /appointments/export, added for a one-off migration, has no use case and returns every patient's appointments to any appt:read token. It is deleted.
Patient lacks insurance:check. The booking service forwards the caller's token to the eligibility service, so every patient booking would fail with a 403. Integration tests used an admin token and missed it.
Front Desk holds rx:write, granted during testing. No front desk use case needs it, and prescription write access for non-clinicians is a reportable audit finding.
Reschedule appointment has no endpoint: design assumed cancel-and-rebook, product assumed a dedicated flow. Settled in 20 minutes, before launch.

At 14 endpoints this is a spreadsheet. A year later, at 120 endpoints and 30 roles, the same check runs in CI on every change to the spec or the roles.

Trade-offs

Option	Strengths	Weaknesses	Choose when
Use case diagram plus written scenarios	Scope, roles and failure cases agreed early	Two artefacts to keep in step	New product areas, regulated domains
User stories only	Small, fits sprint planning	No single view of who can do what	Small teams, low access-control risk
Diagram generated from route and role metadata	Always matches the code	Shows what exists, not what was intended	Large APIs, audits
Access matrix table, no diagram	Easy to diff and check in CI	Hard to read for non-engineers	Mature systems with many roles

Pitfalls in production

Use cases mirror database tables ("Manage patients"), so the permission model becomes table-level CRUD and over-grants. Fix: name use cases as actor goals and give each its own scope or policy rule.
An included use case calls a downstream service with the caller's token, and callers lack its scope. Fix: propagate include permissions up to every base actor, or have the base call the inclusion with a service identity and document that choice.
Debug or migration endpoints outlive their purpose with no owner. Fix: require every route to declare a use case and fail CI when one does not.
Roles accumulate permissions granted "temporarily" during incidents. Fix: compute least privilege from the matrix and flag every grant no use case needs.
Extend arrows are drawn backwards, so the base team believes it owns the late-fee logic. Fix: the extension points at the base, and the base exposes a named extension point (an event or hook).

Leadership lens

Ask for the access matrix in every design review of a new surface; scope disagreements are cheapest there.
Make "every endpoint names its use case" a merge rule: one annotation per route, and orphaned endpoints cannot ship.
Treat over-granted roles as debt with an owner. Least-privilege reviews are cheap when the needed set is computed, not argued.
Keep the diagram at actor-goal level; steps belong on an activity or sequence diagram.

Check yourself

Booking always checks insurance; cancelling sometimes charges a fee. Which is include and which is extend, and which way does each arrow point?
Show answer
Insurance is include, pointing from Book to Verify insurance. The fee is extend, pointing from Apply late fee to Cancel, because the base must not depend on the optional behaviour.
Why does an actor need the permissions of use cases it never directly invokes?
Show answer
Included use cases run as part of the base, often with the caller's credentials, so their requirements propagate to every actor of the base.
Billing Admin specializes Front Desk. What does that mean for access?
Show answer
Billing Admin inherits every Front Desk association and grant and adds its own; in RBAC terms its role inherits the Front Desk role.
What does a missing line between an actor and a use case promise?
Show answer
That the role cannot perform it. That negative claim is what least-privilege checks and audits test.

Watch

UML Use Case Diagram Tutorial (Lucid Software): actors, boundaries, include and extend with a worked example.

Free resources

Use case diagram (Wikipedia): the notation and the include, extend and generalization relationships.
Use case (Wikipedia): the written templates behind the ovals, including Cockburn's levels.
Use Case (Martin Fowler): why the text matters more than the diagram.
Use case diagram (PlantUML): diagram-as-code syntax for actors, use cases and boundaries.
Flowchart syntax (Mermaid): subgraphs and node shapes used to approximate use case diagrams.
UML 2.5.1 specification (OMG): the normative definitions of actors, use cases, include and extend.

Open in the interactive app: practice, quiz, mock interview →