Diagrams as Code

Diagrams as code is a term used for storing the source of a diagram image as a text file. Examples include architecture diagrams, or diagrams showing a system’s behavior or design.

A generator tool like PlantUML then generates an image from the text. According to the ThoughtWorks Technology Radar, a key benefit is that you can use version control on the text files.

In this article, I will present an approach that takes the term diagrams as code literally. I will show you how to generate diagrams from source code.

Represent the diagrams as models in Java source code. And run an automated check if the generated diagrams are modeled correctly.

Storing the diagrams as source code makes it more likely that they get updated continously when the code changes. Plus you get better syntax highlighting and auto-completion, compared to solutions like PlantUML.

Getting started

The diagrams as code library that I created is available on GitHub and Maven Central.

You can use Maven or Gradle as build tools to get access to the diagrams as code library that I created.

If you are using Maven, include the following in your POM:

<dependency>
  <groupId>org.diagramsascode</groupId>
  <artifactId>diagramsascode-image</artifactId>
  <version>0.1.1</version>
</dependency>

If you are using Gradle, include the following in your build.gradle:

implementation 'org.diagramsascode:diagramsascode-image:0.1.1'

The jar files are also available in the ‘Releases’ section of the GitHub page.

Generating a sequence diagram

First, I’ll show you how to create a sequence diagram. Sequence diagrams are useful to show the interactions of participants. A participant could be your whole application. It could be an application component. Or a single class.

To interact with each other, the participants send and receive messages.

Let’s have a look at a simple example. There are 2 participants, a Client and a Server. The Client sends a Request Message to the Server, which responds with a Response Message. This is the diagram:

In a real world application, the interaction patterns can be much more complex. That’s when sequence diagrams pay off. Looking at the sequence diagrams helps developers understand what happens at a glance.

To create the participants and messages, you use this code:

// Create the participants (that exchange messages)
var participant1  = new Participant("Client");
var participant2  = new Participant("Server");

// Create the request and response message
var message1 = new Message(participant1, participant2, "Request Message");
var message2 = new Message(participant2, participant1, "Response Message");

Once you’ve build the diagram elements, you can build the diagram model:

// Build the diagram
var diagram = Diagram.builder()
  .withNodes(participant1, participant2)
  .withEdges(message1, message2)
  .withConstraints(new SequenceDiagramConstraints())
  .build();

As you can see, you pass in the participants as nodes, and the messages as edges. But what does the following line mean?

.withConstraints(new SequenceDiagramConstraints())

Use constraints to validate that the contents of the diagrams are correct. For sequence diagrams, these constraints are:

• The diagram only shows sequence diagram nodes, i.e. participants
• The diagram only shows sequence diagram edges, i.e. messages
• Each participant has a name

You can omit validating constraints by skipping the .withConstraints(...) part when building the diagram. This is not recommended in general. It allows building invalid diagrams. But it may be useful for prototyping.

Once you’ve build the diagram model, you can generate the diagram image and write it to a file on disk. The following code writes it to a file stored in the temporary directory:

// Create the image of the diagram and write it to a PNG file.
var outputFile = File.createTempFile("sequence", ".png");
SequenceDiagramImage.of(diagram).writeToPngFile(outputFile);

System.out.println("Sequence diagram written to: " + outputFile);

Conclusion

In this article, I’ve shown you a way to generate diagrams for source code. Diagrams can improve your understanding of what happens in your application. And your communication with fellow developers.

Apart from sequence diagrams, the library can also generate activity diagrams. Have a look at the diagrams as code GitHub page for details.

For the future, I plan to support class diagrams as well.

What are your thoughts? Please leave a comment to give me feedback.