Use Case Diagrams

UML Use Case Diagram Notation

Use case diagrams show who interacts with your system and what they can do — at a glance. They are especially useful for communicating system scope to non-technical stakeholders.

Core elements:

• Actor: Drawn as a stick figure. Primary actors (initiate interactions) on the left. Secondary actors (respond to system calls) on the right.
• Use Case: Drawn as an oval with a descriptive label inside. Always a verb phrase: "Place Order," "Send Email," "Authenticate User."
• System Boundary: A rectangle labeled with the system name. All use cases inside; all actors outside.
• Association: A solid line connecting an actor to a use case they participate in.

Relationships Between Use Cases

<<include>>: A mandatory dependency. Use case A always invokes use case B. Drawn as a dashed arrow from A to B labeled <<include>>.

Example: "Place Order" includes "Calculate Tax" — you cannot place an order without tax being calculated.

<<extend>>: An optional addition. Use case B sometimes extends use case A under specific conditions. Drawn as a dashed arrow from B to A labeled <<extend>>.

Example: "Log In" may be extended by "Complete MFA Challenge" — but only when the user has MFA enabled. The extension point is optional.

Generalization (inheritance): A solid arrow with a hollow arrowhead, same as UML class inheritance. Used for actors (Admin extends User — admin can do everything a user can plus more) or use cases (specialization).

When Diagrams Help vs Over-Complicate

Helpful when:

• Communicating system scope and boundaries to non-technical stakeholders
• Identifying missing use cases during requirements review
• Onboarding new team members to an existing system
• Defining integration points with external systems or actors

Over-complicates when:

• The system has fewer than 5 use cases (just describe them in prose)
• The audience is a single developer building a well-understood feature
• You find yourself modeling every sub-step instead of staying at goal level

Mermaid.js: Diagrams as Code

Mermaid.js lets you write diagrams as text in markdown, which renders automatically in GitHub, Notion, and documentation tools. No design tool required.

graph TD
  Student -->|browses| ViewCourse
  Student -->|enrolls in| EnrollCourse
  Student -->|submits| SubmitAssignment
  Instructor -->|creates| CreateCourse
  Instructor -->|grades| GradeSubmission
  Admin -->|manages| ManageUsers
  Admin -->|views| ViewAnalytics

For actual UML use case diagrams, use a block diagram with actor labels:

flowchart LR
  subgraph System["Learning Platform"]
    ViewCourse["Browse Courses"]
    Enroll["Enroll in Course"]
    Watch["Watch Lessons"]
    Submit["Submit Assignment"]
    Grade["Grade Assignment"]
  end
  Student --- ViewCourse
  Student --- Enroll
  Student --- Watch
  Student --- Submit
  Instructor --- Grade
  Enroll -.->|includes| ProcessPayment["Process Payment"]

Tool Spotlight

Mermaid.js — Write diagrams as code in markdown. Renders in GitHub READMEs, GitLab, Notion, and Obsidian. Free and open-source. Best for developer-owned documentation.

Lucidchart — Visual drag-and-drop diagramming with UML shape libraries and real-time collaboration. Free tier for up to 3 documents.

Draw.io (diagrams.net) — Free, open-source, works in browser and integrates with Google Drive and VS Code. The best free option for formal UML diagrams.

PlantUML — Text-to-diagram like Mermaid but with explicit UML support including proper use case diagram syntax. Renders via server or local Java. Best for teams that need strict UML compliance.

Key Takeaways

• Use case diagrams show actors (stick figures), use cases (ovals), and a system boundary (rectangle)
• <<include>> is mandatory — A always calls B. <<extend>> is optional — B sometimes extends A
• Generalization (inheritance) applies to both actors and use cases
• Diagrams help stakeholder communication and scope reviews — avoid them for simple, obvious features
• Mermaid.js lets you write diagrams as code inside markdown, keeping documentation close to the code