Explaining Class Diagrams in Mermaid

The aim of this page📝 is to introduce the Mermaid class diagram as a domain modeling tool, the way of determining the important aspects of a business, often comprised of stakeholder + product + engineering. I am just sharing personal notes from reading a respective chapters of the wonderful Ashley Peacock’s book — read (and buy!) the whole thing! He has made me a convert at his podcast appearance in SE Radio 566: Ashley Peacock on Diagramming in Software Engineering : Software Engineering Radio

Pavol Kutaj
4 min readAug 29


class diagram is used for the visualization of domain models/business logic + data

When creating the domain model, start with the entity identification

  • entity is a concept from DDD
  • relevant also for Snowplow tracking where it is also known as a context is a core concept within the business
  • entities are basic categories in the language of the domain and therefore meetings with stakeholders
  • in a codebase, entities are represented by
  • data
  • business logic

#1 rel type: called bi-directional association - loose bidirectional partnership

  • interpretation: Title is associated with a certain genre
  • representation: Title -- Genre
  • association is one type of relationship in UML
  • this is bidirectional association where both entities are holding the association to the opposite one
  • there are other types, too
  • it is the loosest type, the entities
  • exist independently, i.e. they are meaningful on their own
  • have their lifecycles
  • there is no owner
  • the entities are using one another, not owning one another

#2 rel type: composition relationship - tight ownership

  • interpretation: Title has one or more Seasons
  • representation: Title *-- Season
  • composition is more of a parent-child relationship
  • child cannot exist without a parent!
  • in UML/Mermaid, composition is represented with *

the first diagram with two extra rules: parents on the left & whitespace for natural divisions

  • rule#1 is to put parent always on the left, therefore * on the left. The parent is a star
  • rule#2 is to use white space to make a natural division between various parents
Title -- Genre
Title *-- Season
Title *-- Review

Season *-- Episode

#3 rel type aggregation - loose ownership

  • interpretation: Title features one or many actors
  • representation: Title o-- Actors
  • however, actors can live without a particular title — as opposed to a season or a review
  • aggregation is also a type of ownership — but a loose ownership
Title -- Genre
Title *-- Season
Title *-- Review
Title o-- Actors

Season *-- Episode

#4 rel type: inheritance - generalization

  • interpretation: TV Show or Film is implementing a Title
  • representation:
  • with --|> rendered as an arrow pointing to the parent using the usual implements as a verb
  • Mermaid supports inheritance with a concept of generalization
Title -- Genre
Title *-- Season
Title *-- Review
Title o-- Actor
TV_Show --|> Title
Short --|> Title
Film --|> Title
Season *-- Episode
Season *-- Review
Episode *-- Review
  • Comments in Mermaid are used with %%

#5 rel type: directional association - directed loose partnerships

  • interpretation: Viewer watches Title, but Title does not know about Viewer
  • representation: Viewer --> Title
  • the bidirectional association (#1 rel type) rendered with -- can be enriched with an arrow < or > (left to right is correct)
  • in this particular case
  • Viewer holds a reference to Title
  • Title does not hold a reference to Viewer

#1 addition — verbs describing the relationship with : <verb> after the relationship

Title -- Genre: is associated with
Title *-- Season: has
Title *-- Review: has
Title o-- Actor: features

TV_Show --|> Title: implements
Film --|> Title: implements
Short --|> Title: implements

Viewer --> Title: watches

Season *-- Review: has
Season *-- Episode: contains

Episode *-- Review: has

#2 addition — multiplicity with "<int>" or "<int>...*" before

  • multiplicity is another word for cardinality
  • it’s a data relationship type (relationship in the meaning of relational database)
  • e.g. one-to-one, one-to-many, none-to-many, many-to-many, and everything in between (for example, more unusual ones such as two-to-three)
Title "1..*" -- "1..*" Genre: is associated with
Title "1..*" *-- "1..*" Season: has
Title "1" *-- "0..*" Review: has
Title "0..*" o-- "1..*" Actor: has

#3 addition: Title with front matter starting with ---

  • similar to the front matter of Jekyll docs, you can add
  • usually set variables and metadata for the page, such as the title, layout, and permalink. The front matter is written in YAML and is enclosed by triple-dashed lines
title: Foobar Domain Model

Title "1..*" -- "1..*" Genre: is associated with
Title "1..*" *-- "1..*" Season: has
Title "1" *-- "0..*" Review: has
Title "0..*" o-- "1..*" Actor: has




Pavol Kutaj

Today I Learnt | Infrastructure Support Engineer at snowplow.io with a passion for cloud infrastructure/terraform/python/docs. More at https://pavol.kutaj.com