Creating Mermaid Use-Case Diagrams

Welcome to the next step in your training. In our last session, we focused on the analytical groundwork for requirements modeling, learning how to dissect a scenario to identify actors, use cases, and the all-important system boundary. You now have the conceptual tools to understand a system's functional requirements from a user's perspective.

Today, we will translate that conceptual understanding into a concrete visual artifact. This lesson directly addresses the learning outcome of creating a Mermaid flowchart that approximates a UML use case diagram. You'll learn how to represent actors and their interactions with a system, and critically, how to handle the inevitable gaps between pure UML notation and what's practical to implement in Mermaid. This is a core skill for producing effective, maintainable "diagrams as code".

Bridging the Gap: From UML to Mermaid Flowcharts

The first thing to know is that Mermaid does not have a native useCaseDiagram type. This might seem like a limitation, but in practice, we can create a very effective and readable approximation using Mermaid's most versatile tool: the flowchart. Your experience in front-end development has likely shown that perfect, pixel-for-pixel adherence to a design isn't always as important as correctly implementing the functional structure—the same principle applies here.

We will map the UML concepts you learned previously to Mermaid flowchart syntax:

• Use Case (UML Oval): We'll represent this with a Mermaid node. A rounded rectangle () is a good visual analog for the UML oval.
• Actor (UML Stick Figure): We can represent this as a distinct node, perhaps using an emoji for clarity, like actor["👤 Actor"].
• Association (UML Line): This maps directly to a standard flowchart link, -->.
• System Boundary (UML Rectangle): This can be represented by a Mermaid subgraph, which creates a visual container for all the use cases.

This approach gives us a clean, semantically correct structure that mirrors the formal UML diagram.

The "System as a Box" Pattern

Let's formalize this. The most correct way to model a use case diagram in Mermaid is to treat the system as a container for its functions.

1. Actors are defined as nodes outside the system.
2. The System Boundary is a subgraph.
3. Use Cases are nodes defined inside the subgraph.
4. Associations are links from the external actor nodes to the internal use case nodes.

Here is a simple example in Mermaid code:

This structure is clear and maintains the logical separation between what is inside and outside the system, which is the primary purpose of a use case diagram.

An Alternative: The "Actor-Centric" Pattern

While the "System as a Box" pattern is formally correct, you will sometimes see another pattern used in practice. This alternative groups use cases by the actor who performs them, using a subgraph for each actor. This pattern is less concerned with the system boundary and more focused on answering the question, "What can this type of user do?"

The following resource from IBM's documentation demonstrates this actor-centric approach. It's a pragmatic choice that can be very readable for complex systems with many distinct user roles.

The key tradeoff is this:

• System as a Box: Excellent for showing system scope and boundaries. Formally correct.
• Actor-Centric: Excellent for showing roles and responsibilities. Can be more readable when you have many actors with distinct capabilities.

As a developer, knowing both patterns allows you to choose the best visualization for your specific documentation goal.

Handling Unsupported UML Relationships

The simple association --> is easy, but what about the more specialized relationships you've seen in UML, like <> , <>, and generalization (inheritance)?

Let's quickly review what these are for, using the "UML use case diagrams: Everything you need to know" video. Watching these short clips will refresh your memory on what a "full" UML diagram can express.

Mermaid's flowchart syntax has no built-in equivalent for these three relationships. This is the most significant gap you must document. You have a few options:

1. Ignore them: For a very high-level overview, this can be acceptable.
2. Use link text: You can add text to a link, like A -- "<<include>>" --> B. This can quickly make the diagram cluttered and hard to read.
3. Use comments (Good Practice): Mermaid supports comments using %%. You can add a comment to explain the nature of a relationship, keeping the visual diagram clean.

4. Use surrounding Markdown text (Best Practice): Often, the clearest method is to keep the diagram simple and explain the complex relationships in the text accompanying the diagram. The diagram shows that a relationship exists; the text explains what kind of relationship it is. This aligns well with the "diagrams as code" philosophy, where diagrams are embedded within richer documentation.

A Note on Shapes and Subgraphs

The ability to create different node shapes and group them in subgraphs is central to our approximation strategy. The technical paper below provides more detail on how these flowchart elements work in Mermaid. You don't need to read it in full, but knowing it exists is useful if you ever need to create more complex approximations.

Practice: Diagramming a Course Platform

Now, let's put this into practice. Consider a simple online course platform with the following requirements:

• A Student can Browse Courses, Enroll in a Course, View Course Content, and Submit an Assignment.
• An Instructor can Create a Course and Grade an Assignment.
• To Enroll in a Course, a student must always also Make a Payment. This is a classic <> relationship.

Your task:
Create a use case diagram approximation in Mermaid for this scenario using the "System as a Box" pattern. Be sure to document the <> relationship between Enroll in a Course and Make a Payment using a Mermaid comment.

Try to construct the diagram yourself first in a text editor or the Mermaid Live Editor. Once you have attempted it, compare your result to the solution below.

Click to see the solution

(Note: I added a link from Instructor to Submit an Assignment to show they interact with it via grading. The exact associations can vary based on interpretation, which is normal in modeling.)

Conclusion

In this lesson, you have bridged the gap between the theory of use case analysis and the practical reality of creating diagrams with Mermaid. You've learned how to create a robust approximation of a UML use case diagram using flowcharts.

Here are the key takeaways:

• Mermaid approximates UML use case diagrams using its flowchart syntax.
• There are two main patterns for this approximation: the formally correct "System as a Box" and the pragmatic "Actor-Centric" model. Choosing between them depends on your documentation goals.
• Node shapes () and [], subgraphs, and links --> are the building blocks.
• Specialized UML relationships like <>, <>, and generalization are not natively supported. You must document them using comments (%%) or surrounding text.

In our next lesson, we will continue exploring business workflows. You'll learn to model the internal logic of a single use case using concepts from UML Activity Diagrams, which map very naturally to Mermaid's flowchart capabilities. You will see how these different diagrams work together to provide views of a system at different levels of detail.