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, Draw.io, 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.
Conclusion
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.
References:
[1]: C4 Model – Unlock Effective Collaboration – NashTech Insights
[2]: Diagram as Code for prototyping cloud system architectures
[4]: PlantUML – Generate diagrams from textual description
