"Diagram as code"

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.

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

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 mentioned the growth of such an approach in this post. 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 dialects:

• Plantuml for C4, yes we use C4 for the architecture documentation because we like the simplicity of the modeling and also the idea of navigability. We use then
• Plantuml for AWS as our application is deployed on AWS, but you can also find versions for
• Azure, or
• GCP.

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

everything versionable

Now we have everything versionable. We can finally compare diagrams. As Simon Brown says, we are just diagraming, not modeling, and it is true. With the latest improvements of structurizr 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 plugin to generate SVG with embed URLs
• plantuml for C4 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 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.