NashTech Insights

Diagram as Code with C4 Model – Why Not

Tien Nguyen
Tien Nguyen
Table of Contents
woman working at home using her laptop

Common Problems with Drawing Tools

Architectural visualization defines how architectural models are depicted, and how stakeholders interact with those depiction.

– Taylor, Medvidovic, Dashofy – Software Architecture: Foundations, Theory, and Practice

As we both know; Architectural Visualization plays a critical role in software design and modeling. It provides the means that helps visually communicate and analyze the complex architectural concepts and structures. Commonly, there are two key aspects that can impact to the quality of the visualization:

  • Depiction – a picture or visual representation of the architectural design decisions in a particular format.
  • Interaction – the mechanisms which stakeholders can interact with the decisions in terms of the depiction.

There is a huge set of drawing tools that we can use to produce these diagrams (e.g., Microsoft Visio,, OmniGraffle). These tools allow us to create image-based output to embed into other documents or web pages, while other tools such as Gliffy, Lucidchart provide a direct integration with Wiki platform like Atlassian Confluence. Along with C4 Model [1], we are able to compose artifacts we need for our communication.

However, simply having good and clear diagrams is not sufficient. It is often tempting to invest a significant amount of time in making them visually appealing and ensuring consistency. Additionally, the diagram versioning arises as another challenge.

Diagram As Code – The New Approach

The concept of “Everything-As-Code” has gained popularity in recent years including Operations-As-Code, Infrastructure-As-Code, Configuration-As-Code and Policy-As-Code. By embracing this methodology, organizations can achieve the philosophy of Operational Excellence such as:

  • Gaining the consistency, scalability, and portability across a larger environment.
  • Enabling the versioning control.
  • Building up the auditability across the organization.

As part of this approach, Diagram-As-Code is a preferred method for resolving the issues encountered with the traditional drawing tools. Recently, there are several tools built with this concept in mind, including Diagram [2], Mermaid [3], PlantUML [4], and Structurizr [5]. Notably, Structurizr specifically supports the C4 Model and offers interactive, embeddable diagrams with automatically generated legends.

Tooling & Sample

With Docker, VSCode, and structurizr/lite image, creating and updating software architecture models becomes seamless. By simply setting up a web-based container locally, we can efficiently develop and maintain these models.

docker run -it --rm -p 8080:8080 -v {YOUR_ROOT_DIR}:/usr/local/structurizr structurizr/lite

Moreover, the structurizr image can also be integrated with a pipeline to generate an internal web-based view container. This container then serves as a valuable tool for internal team review and communication, enabling direct interaction within the web view.

Reaching out for more information about sample diagram sets on my GitHub [6] sample.


Using “Diagram-As-Code with C4 Model” revolutionizes software architecture documentation by combining visual diagrams with the flexibility of code. It enables teams to efficiently collaborate, scale, and evolve their systems by representing components, relationships, and behavior in a standardized, machine-readable format. By automating diagram generation, version control, and ensuring consistency, we can optimize the documentation process, enhances communication, and facilitates the creation of effective and sustainable software architectures.


[1]: C4 Model – Unlock Effective Collaboration – NashTech Insights

[2]: Diagram as Code for prototyping cloud system architectures

[3]: Mermaid – Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

[4]: PlantUML – Generate diagrams from textual description

[5]: Structurizr – C4 models as code

[6]: C4 diagram-as-code sample that use Structurizr DSL

Tien Nguyen

Tien Nguyen

Tien is an Engineering Manager at NashTech Vietnam. With over 12 years of experience in the field of software development, he specializes in web development and modernization, have extensive knowledge of PHP and Python technology stack. He also passionate about AWS cloud services and software architecture.

Leave a Comment

Your email address will not be published. Required fields are marked *

Suggested Article

%d bloggers like this: