Diagram as Code

In an age where software development is evolving rapidly, it’s increasingly vital for developers to represent and communicate complex systems and flows visually. Traditionally, these representations have taken the form of diagrams generated by various GUI-based tools. However, these tools have several shortcomings - they can be hard to version control, compatible with text-based collaborative tools, and cumbersome to use in rapidly changing software environments.

“Diagram as Code” represents a paradigm shift in the creation and management of diagrams. It uses a textual, code-like representation to generate diagrams, functioning much like a compiler that translates source code into an executable program. This approach converts diagrams into text files that can be managed just like any other piece of code.

The real magic lies in its seamless integration with modern software development practices. Since diagrams are expressed as code, they can be versioned using standard tools like Git, enabling developers to keep track of changes over time. Collaborating on diagram updates becomes as straightforward as collaborating on code changes. Automated documentation processes can also be extended to include diagrams, ensuring consistency between diagrams and their corresponding code or documentation.

The Problems with Traditional Diagramming Tools

As the complexity of our software systems grows, so does the complexity of our diagrams, and traditional diagramming tools often fall short of meeting these demands. Let’s delve into some of the challenges presented by these traditional tools.

*1. Lack of Version Control*

Unlike text files, diagrams created using graphical tools are often saved in binary or proprietary formats, which makes it difficult to track changes over time. It is particularly problematic in an environment where software and systems constantly evolve, and diagrams must be updated accordingly. Without proper version control, you’re left with either a pile of outdated diagrams or numerous versions of the same diagram with no clear history of what changed and when.

*2. Collaboration Difficulties*

Collaboration is another challenge when working with traditional diagramming tools. Often, these tools are desktop-based and do not inherently support collaborative editing. Even with cloud-based solutions, simultaneous editing may lead to conflicts and inconsistencies. In addition, diagrams saved in proprietary formats may not render correctly across different platforms or software versions, adding another layer of complexity to collaborative efforts.

*3. Inefficiency and Inconsistency*

Creating and updating diagrams with GUI-based tools can be time-consuming, particularly for complex diagrams. It often results in diagrams being created once and then never updated, leading to a disconnect between the current state of the system and its visual representation. Additionally, every team member may have their own style of creating diagrams, leading to inconsistencies across a single project or organization.

*4. Integration with Developer Tools and Workflows*

Traditional diagramming tools often operate in isolation from other developer tools and workflows. They’re not designed to integrate with text editors, version control systems, or continuous integration/continuous deployment (CI/CD) pipelines. This lack of integration makes it harder to maintain up-to-date diagrams as part of the codebase or the development workflow.

Transitioning to a New Paradigm: Diagram as Code

Reflecting on the mentioned problems, we can see a common theme: the traditional approach to diagramming, though useful in certain contexts, is often at odds with the dynamic, collaborative, and integrated nature of modern software development. So, how can we better align the diagramming process with the needs and practices of contemporary software development?

“Diagram as Code” could be considered a revolutionary way to create and manage diagrams. It extends the principles of code – text-based, versionable, collaborative – to the world of diagrams.

*1. Addressing Version Control*

With “Diagram as Code,” all diagrams would be stored as text files, just like their source code. Every change would be a change to the text file, which means it could be tracked using the same version control system they use for their codebase. They could easily view or revert to any previous diagram version right from their Git history.

*2. Streamlining Collaboration*

For the globally distributed team struggling with conflicting diagram updates, “Diagram as Code” offers an effective solution. The team members can now edit the diagram like any code file. They can work independently on different parts of the diagram and then merge their changes using standard Git workflows. There are no more conflicting updates and no more manual merging.

*3. Enhancing Efficiency and Consistency*

The solo developer, frustrated with the time-consuming process of updating his flowchart, would find “Diagram as Code” a boon. He can update the code instead of manually adjusting shapes and lines whenever the process changes. The updated code generates the diagram, ensuring it always reflects the current process. And since the visual appearance of the diagram is controlled by the tool, all diagrams created by the team will have a consistent look and feel.

*4. Integrating with Developer Workflows*

Lastly, the team that wanted to include their database schema diagrams in their documentation would greatly benefit from “Diagram as Code.” They can write code describing their database schema, then set up a tool to automatically generate the diagram as part of their documentation build process. Any changes to the schema will be reflected in the diagram as soon as the documentation is rebuilt.

Understanding the Challenges

While “Diagram as Code” offers numerous advantages and can be a game-changer for software development, it’s important to recognize that transitioning from traditional GUI-based diagramming tools to a code-based approach can pose challenges. Let’s discuss some of these potential hurdles.

*1. Learning Curve*

Every new tool or approach comes with a learning curve, and “Diagram as Code” is no exception. Teams need to learn a new syntax to define diagrams, and it may require a shift in mindset, especially for those accustomed to drawing diagrams using a GUI.

*2. Limited Visual Customization*

Traditional GUI-based tools typically provide extensive options for customizing the appearance of your diagrams, such as colors, fonts, and shapes. “Diagram as Code” tools often have more limited customization options since they aim to standardize the diagram’s appearance to enhance readability and consistency.

*3. Difficulties with Complex Diagrams*

While “Diagram as Code” tools excel at creating certain types of diagrams, they may be less effective for highly complex or artistic diagrams that require intricate details and layouts. A GUI-based tool might still be a better choice for these types of diagrams.

*4. Resistance to Change*

Like any change in process or tooling, adopting “Diagram as Code” may meet resistance from team members who are comfortable with the existing way of doing things. This challenge can be mitigated with clear communication about the benefits of the new approach and by providing adequate training and support during the transition period.

Available Tools

Several tools have emerged in the “Diagram as Code” field, each with unique strengths and capabilities. Here, we’ll explore some of the most popular ones.

**Graphviz**: Graphviz is a powerful, open-source graph visualization software with a scripting language known as DOT. It’s particularly well-suited for representing structural information such as software diagrams, network diagrams, data flow, and other intricate graph structures.

**PlantUML**: PlantUML is an open-source tool that allows you to create UML diagrams using a simple and intuitive language. It supports various diagram types, including sequence diagrams, use case diagrams, class diagrams, activity diagrams, and more. It’s based on Graphviz for diagram layouts and written in Java.

**Mermaid**: Mermaid is a popular open-source JavaScript-based diagramming and charting tool. It uses a markdown-like syntax to generate flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, pie charts, and more.

**Structurizr**: Structurizr is a collection of tooling to create software architecture diagrams and documentation based on the C4 model. It provides open-source libraries (Java and .NET) and a commercial SaaS offering for creating, managing, and sharing diagrams.

**D2 (Declarative Diagramming)**: D2 is a versatile tool that uses declarative language for diagramming, enabling a uniform way to describe and manage diagrams. It’s an open-source project and supports a wide range of diagrams.

**Diagrams**: Diagrams is an open-source Python library that allows you to build cloud system architecture diagrams with just Python code. It’s an excellent tool for generating complex, professional-quality infrastructure diagrams.

**Diagrams.net**: While not a “Diagram as Code” tool in the traditional sense, diagrams.net is a free, open-source online diagramming tool that supports importing diagrams defined in XML format, enabling a form of diagram-as-code approach. It supports a wide variety of diagram types and offers extensive customization options.

Tech News

memo Fearing leaks, Apple restricts ChatGPT use among employees

Yoga: “Apple has restricted employee access to ChatGPT and AI coding tools, fearing potential data leaks. They are developing their own AI technology, while Microsoft plans to release a privacy-focused version of ChatGPT. However, Apple users can still access ChatGPT through an official iPhone client.”

memo Read from and write to a serial port

Brain: “The Web Serial API, launched in Chrome 89 as part of the capabilities project, enables websites to establish bidirectional communication with serial devices such as microcontrollers and 3D printers. The API allows for enhanced user experiences in various sectors, including education, hobbies, and industry, by providing a way to read from and write to serial devices using JavaScript. Previously, websites relied on agent applications, packaged applications, or manual installation steps for device communication, but the Web Serial API simplifies the process and facilitates direct interaction between websites and the controlled devices.”

memo Windows 11 to Introduce Force Quit and Native Archive Format Support for Enhanced Functionality

Rizqun: “Windows 11 will soon add a force quit option to the taskbar, enabling users to close crashed or problematic apps directly without using the Task Manager. Additionally, the update will introduce native support for archive formats such as RAR, Tar, 7-zip, and gz. These enhancements aim to improve the user experience and functionality of Windows 11. All these new features should arrive in the coming months for all Windows 11 users.”

memo Please, no Cosmos DB with EntityFramework

Dika: “The article advises against using Entity Framework with Cosmos DB due to several drawbacks. Entity Framework offers development speed and convenience but can cause performance issues and abstract the actual queries being executed. Cosmos DB, on the other hand, excels at document storage and global scalability but struggles with expensive cross-partition queries. The article recommends using Cosmos DB directly and avoiding the Entity Framework provider to minimize complications and ensure optimal usage of each technology.”

memo Technology Lifecycle - Managing Expectations for Infrastructure Projects

Frandi: “Slack Engineering team shares how they use the technology lifecycle framework to manage the development, support, and retirement of infrastructure projects. They describe the six stages of the technology lifecycle: Experiment, Beta, Active, Maintenance, Deprecated, and Retired. They illustrate how they used the framework to migrate through three iterations of a platform offering, from BuiltBySlack to Bedrock, and how they communicated and planned with their customers and peers.”