Using Github and MermaidJs to Document Software Architecture Using C4 Model
Tags: architecture, c4model, mermaidjs
Published: 2022-03-15 12:30:24

---
title: Using Github and MermaidJs to Document Software Architecture Using C4 Model
published: true
description: Using Github and MermaidJs to Document Software Architecture Using C4 Model
tags: softwarearchitecture, c4model, mermaidjs
//cover_image: https://direct_url_to_image.jpg
---

UML is a popular standard for developing software architecture. But it has an alternative in thee C4 model. The C4 model is an "abstraction-first" approach to diagramming software architecture, based upon abstractions that reflect how software architects and developers think about and build software. For more information about the C4 model, please visit [its website](https://c4model.com).

The C4 model consists of hierarchical diagrams in 4 steps:
1. The System **Context** Diagram
2. **Container** Diagram showing the independently deployable parts of the sytem.
3. **Components** of the containers
4. **Code**

More information is made available as we go down the hierarchy, more like zooming into a map. To be able to visualize C4 models, we have to have a system that is able to take us from one item up in the hierarchy to its children down the hierarchy. There are not that many tools that are able to work with C4 models yet, these being limited to:

1. [Gaphor](https://gaphor.org/). This is a free desktop application
2. [C4-plantuml](https://github.com/plantuml-stdlib/C4-PlantUML) which provides a VS-Code extension
3. [goadesign](https://github.com/goadesign/model) for creating software architecture models and diagrams in Go
4. [structurizr](https://structurizr.com/) which is proprietary software from Simon Brown, the developer of the C4 model.
5. MermaidJs, which is free and can be used in github markdown files.

We are going to show how to build simple models using mermaid JS, with an example available at [mermaid-c4-model](https://github.com/csymapp/mermaid-c4-model)

## Using mermaid in a github md file
Include a code section with mermaid as the language:

~~~
```mermaid
% mermaid code goes here
```
## Choosing Diagram type
Mermaid supports a number of diagram types. We will use `flowchart TB` for our C4 model diagrams.

~~~
```mermaid
flowchart TB
% the rest of mermaid code goes here
```

## Using Subgraphs
MermaidJs was not intended for building diagrams with a lot of information as in the detailed C4 model diagrams. 
![User Diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/em7g9iqegfyb1wix6lj6.png)
Consider the user diagram for example. We cannot possibly include all that info in a single mermaid object. So we choose `subgraphs` as our basic units. We will still not be able to get the icons into the subgraphs. But they are not absolutely necessary.

To build the user diagram above in mermaid, we use a subgraph and 2 other objects (A1 and B1) inside the subgraph. The subgraph and A1 have the same color applied to them. B1 can retain have the default object color.
```mermaid
% color definition
classDef gray fill:#62524F, color:#fff
subgraph publicUser[ ]
    A1[[Public User<br/> Via REST API]]
    B1[Backend Services/<br/>frontend services]
end
% Apply the color to subgraph and A1
class publicUser,A1 gray
```

The result is:
![userDiagramMermaid](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8g1o8m1n57mnj3xdeewy.png)



Each subgraph representing a single object has an `Ai` and a `Bi` object. Where `i` is the number of the subgraph. When applying a color or any other style, we apply it to both the `subgraph` and the `Ai` object.

## Using Legends
A different mermaid object is used to create the legend. A subgraph holds different objects having different colors applied representing the different types of elements in the model, with a description in the object text. For example, the legend below is created using the following code:

![Legend Example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dfaogxlp75o7man6wuwp.png)

```mermaid
flowchart TB
classDef borderless stroke-width:0px
classDef darkBlue fill:#00008B, color:#fff
classDef brightBlue fill:#6082B6, color:#fff
classDef gray fill:#62524F, color:#fff
classDef gray2 fill:#4F625B, color:#fff

subgraph Legend[Legend]
    Legend1[person]
    Legend2[system]
    Legend3[external person]
    Legend4[external system]
end
class Legend1 darkBlue
class Legend2 brightBlue
class Legend3 gray
class Legend4 gray2
```

## Opening Container Diagrams from Context Diagram and going further down the hierarchy
To open a container diagram, we implement a `click` event handler on the object representing the system having the container diagram. In the following example, the Books system has a container diagram representing more detailed info about the system.
![Context Diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/x8l58wzk6u52szt359fy.png)
To open the container diagram, we implement:
```mermaid
subgraph booksSystem[ ]
    A3[[Books System]]
    B3[Allows interacting with book records]
end
class booksSystem,A3 brightBlue

click A3 "/csymapp/mermaid-c4-model/blob/master/containerDiagram.md" "booksSystem"
```
The click event does not work with subgraphs. That is why we use `A3` instead of `booksSystem`.
The url supplied has to be either absolute pointing to the container diagram, or relative to 'https://github.com'. It seems that we cannot supply a path relative to our repo yet. This means that if this repo is forked, then the path has to be editted to reflect its new location.

The same is done for opening a `component diagram` from a `container diagram`.

Since the click event is on the `A` node inside the subgraph, we have to be sure to click on it, rather than on the subgraph itself.

## A little issue
*For large models, github seems not to have a way of scaling it up so that the text and other objects are visible. Zooming in the page does not zoom in the iframe rendering the svg.*

All in all, its a wonderful way to start documenting simple software architectures.

The full example is available in [this github repo](https://github.com/csymapp/mermaid-c4-model).

The C4 model is pretty easy to use, so start designing your software in a way that you can share your design with others.