Recommended resources
The freely available resources this lesson will direct you to.
Welcome to the first lesson in our module on object-oriented structure. In our previous work, we focused on modeling behavior—the dynamic flow of processes using activity diagrams, which you learned to build with Mermaid's flowcharts. We looked at what a system does. Now, we pivot to modeling structure—the static blueprint of the system itself.
This lesson introduces you to UML Class Diagrams, the cornerstone of object-oriented design. Your goal is to learn the fundamental syntax for representing a single class in Mermaid: its name, its data (attributes), and its behaviors (operations). As an experienced developer, you work with classes, attributes, methods, and access control every day. This lesson isn't about teaching you those concepts, but rather about learning the specific visual grammar of UML and the "diagrams as code" syntax of Mermaid to document them precisely.
The Anatomy of a Class Diagram
A class diagram is the primary building block of object-oriented modeling. It visualizes the classes in a system, their internal structure, and the relationships they have with other classes. At its simplest, it provides a blueprint for the code you will write.
A class in a UML diagram is typically drawn as a rectangle with three compartments:
- Top: The name of the class.
- Middle: The attributes (also called fields or properties) of the class. These are the data variables that belong to the class.
- Bottom: The operations (also called methods or functions) of the class. These represent the behaviors the class can perform.
The following video provides an excellent conceptual overview of these components.
This video from Lucid Software, "UML class diagrams," breaks down the fundamental components of a class and the meaning of visibility. It's a great primer on the "what" and "why" before we dive into the "how" with Mermaid.
Please watch these two segments: First, watch from the beginning to the main section. This will introduce the three-part structure of a class (name, attributes, methods) using a clear example. Then, continue watching the next part on visibility. This explains the crucial concept of public, private, protected, and package access levels, which we'll be encoding shortly.
The video introduces the standard UML notation for visibility:
+for public: Accessible from any other class.-for private: Accessible only from within the class itself.#for protected: Accessible within the class and by its subclasses.~for package (orinternal): Accessible by any class within the same package or module.
This concept of encapsulation is fundamental to object-oriented design, and class diagrams make it explicit.
Translating Concepts into Mermaid Syntax
Now that we've reviewed the concepts, let's see how to write them in Mermaid. You'll find the syntax is intuitive and closely resembles pseudocode.
To start any class diagram, you must use the classDiagram keyword on the first line.
Let's look at the official Mermaid documentation to learn the core syntax for defining classes and their members.
This is the official documentation and your primary reference for class diagram syntax. We'll focus on the sections that cover defining classes and their contents.
Please read the following parts of the page: Start at the top and read down to the section "Defining Members of a class". This covers the two main ways to define a class. Continue with the section "Defining Members of a class". The key takeaway here is how Mermaid uses parentheses () to distinguish between methods and attributes. Next, read the subsections on Return Type and Generic Types to see how to add more detail to your member definitions.
As the documentation shows, the basic structure for defining members is straightforward. For example, to create a User class with a public username and a private password hash, the syntax within the classDiagram block would be:
A Practical Walkthrough
Let's see these rules applied in a real-world context. The following video by ArjanCodes is aimed at developers and demonstrates building a class diagram from scratch.
Mermaid JS: Finally There's A Great UML & Diagram Drawing Tool
This segment from "Mermaid JS: Finally There's A Great UML & Diagram Drawing Tool" shows a developer's workflow for creating a class diagram, which will feel very natural to you.
Watch from this section where the presenter builds a class diagram for a payment processing system. Pay close attention to how he: Defines classes for Order, OrderStatus, and PaymentProcessor. Adds attributes (api_key) and methods (connect, process_payment). Applies visibility markers (- for private, + for public, # for protected) to the members of the PaymentProcessor class, explaining the design intent behind each choice.
A Complete Example and Common Pitfalls
For a more comprehensive text-based resource, the following guide provides another excellent walkthrough, a full-scale example, and a valuable list of common errors.
Mermaid Class Diagram: Complete Syntax Guide with Examples ...
This guide reinforces what we've learned with clear tables and a complex example. It also highlights common mistakes, which is incredibly useful when learning new syntax.
First, read the section "How Do You Define a Class?". The table summarizing visibility prefixes is a great reference. Next, it's very helpful to review the common mistakes section. Knowing these in advance will save you debugging time later. Pay particular attention to the notes on missing visibility prefixes and putting the return type in the wrong place.
Here is an example diagram showing a few classes you might find in a game, which uses the syntax we've just covered.
Practice Exercise
Now it's your turn to apply what you've learned. Your task is to model a Repository class, a common pattern in software development for managing data access, perhaps for a Git-like version control system.
Create a Mermaid class diagram for a single class named Repository with the following members:
- Attributes:
name: A public string.path: A private string representing the local file path.remoteUrl: A protected string for the remote server URL.
- Operations:
clone(): A public static method (hint:$suffix) that returns aRepositoryobject.commit(message: String): A public method that returns a boolean.push(): A public method that returns a boolean.connectToRemote(): A private method that returns a boolean.
Use the Mermaid Live Editor or a Markdown file in VS Code to write the code.
Click here to see the solution
Here is one correct way to model the Repository class in Mermaid:
Notice the $ after clone() to mark it as static, and the placement of return types like bool and Repository after the method parentheses.
Conclusion
In this lesson, you've bridged the gap between your existing knowledge of object-oriented programming and the visual language of UML class diagrams, using Mermaid's efficient syntax.
Here are the key takeaways:
- Class diagrams begin with the
classDiagramkeyword. - Classes are defined using the
class ClassName { ... }block structure. - Attributes are defined as
visibility type name, e.g.,-String passwordHash. - Operations are defined as
visibility name(params) returnType, e.g.,+login() bool. The parentheses()are what distinguish them from attributes. - Visibility is explicitly marked with
+(public),-(private),#(protected), or~(package).
You now have the tools to describe the internal structure of any single class. However, the real power of class diagrams comes from showing how classes interact. In our next lesson, we will explore exactly that: defining the relationships between classes, such as association, inheritance, and composition.