Architecting Subsystem Components with UML and Mermaid

Welcome to this new module on system architecture. In previous lessons, we've explored various UML diagrams to model specific aspects of a system, such as its static structure with class diagrams and its dynamic behavior with sequence diagrams. We will now shift our focus to a higher level of abstraction, looking at how a system is organized into major structural blocks.

This lesson addresses how to create a UML component view. You will learn to identify a system's key components, their responsibilities, and the dependencies between them. Since Mermaid doesn't have a dedicated syntax for component diagrams, a key part of our work will be learning how to create a meaningful approximation using other Mermaid diagrams and, crucially, how to document the conventions and notation gaps to ensure your diagrams are clear and unambiguous.

The Component View and the C4 Model

A component diagram in UML is used to show how a system is divided into modular, replaceable parts and the dependencies between those parts. As a front-end developer, you're familiar with breaking down a user interface into a hierarchy of components in frameworks like React or Angular. The concept in software architecture is analogous but applied more broadly: a component can be a group of related classes, a library, a microservice, or any logical block of functionality within an application.

A popular and practical framework for thinking about software architecture diagrams is the C4 model, which stands for Context, Containers, Components, and Code. It provides four levels of zoom to describe a system. The component view corresponds to Level 3.

To get a solid grasp of this concept, let's watch a section of a talk by Simon Brown, the creator of the C4 model. He provides an excellent overview of the model and then zooms into the component level.

As you saw, the component diagram (C4's Level 3) provides a look inside a single "container" (e.g., a web application, an API, or a database). The components shown should correspond to concrete, identifiable units in your codebase, such as modules or packages. The goal is to show the major building blocks and how they collaborate to deliver the container's functionality.

Approximating Component Diagrams in Mermaid

Standard UML has specific notation for components and their interfaces. A component is often shown as a rectangle with a small icon, and it exposes "provided" interfaces (what it offers) and uses "required" interfaces (what it needs).

A standard UML component diagram shows components (like Order Service), their provided interfaces (the "lollipop" symbol for IOrder), and their required interfaces (the "socket" symbol, which connects to a provided interface).

Mermaid does not have a native component diagram type that supports this notation. However, we can create a very effective and readable approximation using a flowchart (graph). This approach is flexible and aligns well with the C4 philosophy of using simple boxes and lines with clear, descriptive text.

Let's model the example from Simon Brown's video: an API application with several internal components.

Here is the structure he described:

• The Single-Page App and Mobile App use the API.
• Inside the API application, there's a Sign-in Controller that uses a Security Component.
• There's also an Accounts Summary Controller that uses a Mainframe Banking System Facade.
• The Security Component and the Facade both interact with a database.

We can represent this using a Mermaid flowchart. Components become nodes, and dependencies become arrows.

Notice a few things about this diagram:

1. Grouping with subgraph: We use a subgraph to clearly define the boundary of the "API Application," just as Simon Brown drew a large box around his components.
2. Descriptive Nodes: Following the advice from the video, the nodes aren't just names. They include the component's name, its technology (e.g., "Spring MVC Rest Controller"), and its primary responsibility. This makes the diagram understandable on its own.
3. Descriptive Edges: The arrows are labeled with the intent of the relationship (e.g., "Makes API calls to," "Uses"). This is far more informative than a simple, unlabeled line.

Documenting Notation Gaps

This diagram is clear, but it's an approximation. We've lost the specific UML notation for provided/required interfaces. To be a good documentarian, you must explicitly state the conventions you've used. This is often done in a legend or in accompanying text.

For the diagram above, your documentation note would look something like this:

Diagram Legend:

• This diagram is a UML Component View approximated using a Mermaid flowchart.
• Rectangles within the "API Application" subgraph represent internal software components.
• Arrows indicate a dependency relationship. The label on the arrow describes the nature of the dependency.
• UML-style provided/required interfaces are not shown directly. Instead, the responsibilities of each component describe the services it offers.

This practice of documenting your modeling choices is critical for maintainability and for helping new team members understand your architecture.

The principles of creating clear, self-contained diagrams are essential. Simon Brown dedicates a significant portion of his talk to these practical tips.

By applying this advice—using explicit descriptions, clear relationship labels, and a legend to explain your conventions—you can overcome Mermaid's limitations and produce architectural views that are just as effective as those made with more complex tools.

Conclusion

In this lesson, you've learned how to conceptualize and construct a UML component diagram, which illustrates the major structural blocks of a software system.

Here are the key takeaways:

• A component view shows the modular decomposition of a system, helping teams understand its internal structure and dependencies.
• The C4 model provides a useful framework, placing the component diagram at "Level 3," which zooms into a specific application or service.
• While Mermaid lacks a native component diagram type, a flowchart (graph) serves as an excellent, flexible tool for creating an approximation.
• To create an effective diagram, you must use descriptive text inside nodes and on edges, and, most importantly, document your conventions and notation gaps in a legend or supplementary text.

In our next lesson, we will zoom out one final time to create a UML deployment view. This will involve mapping the software artifacts and components we've discussed onto the physical or virtual infrastructure where they run, completing our high-level architectural picture.