"Diagram as code"
Tags: architecture, plantuml, productivity, c4model
Published: 2021-01-01 13:08:23

---
title:  "Diagram as code"
published: true
description: 
tags: architecture, plantuml, productivity, c4model
//cover_image: https://direct_url_to_image.jpg
---

We have seen in the [previous article]() that our primary driver is to keep the software documentation as near as possible to the developer, from a tool landscape and also from a process point of view. But if the documentation contains a couple of sentences, there are also many diagrams like the following.

![](https://c4model.com/img/sketch-2.jpg)
*source: https://c4model.com*

a lovely picture from a whiteboard, or if the author took the time to transfer the drawing in a modeling tool, you could have something like that

![](https://i.pinimg.com/564x/80/e2/1b/80e21b2b4f9d1ce8ac3d4f41e4ada86a.jpg)
*source: https://sparxsystems.com*

And in all the cases, it ends with a jpeg or png. Unfortunately, the diagram will evolve, and comparing two jpegs is not so easy :). Following the same approach, documentation as code, it was natural to move to diagrams as code. [Simon Brown](https://twitter.com/simonbrown) mentioned the growth of such an approach in this [post](https://dev.to/simonbrown/diagrams-as-code-20eo). It was comforting to see that the way we were following since the last two years is taking speed.

To make our diagrams versionable and comparable, we use different [plantuml](https://plantuml.com/) dialects:

- [Plantuml for C4](https://github.com/RicardoNiepel/C4-PlantUML), yes we use [C4](https://c4model.com/) for the architecture documentation because we like the simplicity of the modeling and also the idea of navigability. We use then 
- [Plantuml for AWS ](https://github.com/awslabs/aws-icons-for-plantuml) as our application is deployed on AWS, but you can also find versions for
- [Azure](https://github.com/RicardoNiepel/Azure-PlantUML), or
- [GCP](https://github.com/davidholsgrove/gcp-icons-for-plantuml).

And with a simple code like that,

```
@startuml Basic Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
```

we obtain

![](https://andreo.eu/assets/images/2020-12-29-diag/C4.svg)

### everything versionable

Now we have everything versionable. We can finally compare diagrams. As [Simon Brown](https://twitter.com/simonbrown) says, we are just diagraming, not modeling, and it is true. With the latest improvements of [structurizr](https://structurizr.com/) in the direction of `diagram as code` and cloud architecture, we can envisage a migration to such a modeling tool.

Our approach is strongly based on the idea of linking information allowing better navigation, and avoiding redundancy. We wanted to have the same experience at the diagram level, being able to jump into the documentation of the component or in the code directly. To this end, we extended:

- [jekyll-plantuml](https://github.com/yegor256/jekyll-plantuml) plugin to generate SVG with embed URLs
- [plantuml for C4](https://github.com/SebastienAndreo/C4-PlantUML) to naturally embed Url


```
@startuml
!include C4/C4_Container.puml
Person(admin, Administrator, "Alice", {{site.baseurl}}/alice/)
System_Boundary(c1, "Sample System") {
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")
Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")
@enduml
```
Just to be convince, go to the [following url](https://andreo.eu/assets/images/2020-12-29-diag/C4-link.svg) and click on Alice or twitter.

To conclude, a diagram as code is a lightweight manner of documenting your architecture; you can focus on the content and not on tool usage. Give it a try, and if you combine it with jekyll, you have a fully navigable documentation.