In this architect tip, we’re going to be talking about Versionable Architect Diagrams! As always, here at Clear Measure, we are a software architecture company, and our goal for you is to be able to move fast, deliver quality, and run your systems with confidence!
Setup your Versionable Architect Diagrams
Having versionable architect diagrams that work for you is part of that. Now we want to have beautiful diagrams just like this one, but doing them in Visio is just hard. So, let’s get into it.
The first thing that we need to do in order to get started with these types of diagrams, in a versionable fashion, is to install a few Chocolatey components. It’s really easy. You can download the files. If you’ve ever used Chocolatey before, you just run these components; make sure you’re in a powerShell window that’s running as an administrator. After that happens, you open up VS code and install the PlantUML extension.
Immediately after that, you can start creating your own diagrams with PlantUML. Now you can use PlantUML wrong or you can use some C4 extensions, which we’ll talk about. It starts with your development process. If you’ve gotten into our onion DevOps patterns, then this will be very familiar with you, but this is essentially describing a DevOps pipeline for a particular application or for a particular team.
We have our git repository:
- integration build, that kicks off a series of environments that we have with our TV environments or multiple or UAT manual testing,
- environment production, pushing telemetry over to Azure,
- application insights,
- and then all of the deployments, getting the deployable packages from Azure artifacts.
So we want to describe this, but we don’t want to mess with Visio or any of the diagramming tools, and we can do it in text. This is that diagram in text, and we’re using the helpers the Azure PlantUML extensions. You can get those on GitHub.
We define an actor, which is a developer, and we just start using the symbols and their objects. These are methods essentially. So we’re using the symbols, we’re defining the structure, and then we’re defining the process. The actors, the developer, makes a change and pushes to Azure DevOps, and you can see each of the different objects is related either forward or backward with the single hyphen or double hyphen. We can describe what they’re actually doing.
The text that we use to describe them is the text that is painted on the arrow between the symbols. So the text on the left is translated easy, super easy versionable as it’s all text.
System Level Versionable Architect Diagrams
The next type of diagram is the system level diagram. An example is if you’re developing a new system, you already have an ERP system that a supplier uploads a file to and you want a customer to receive a text message. We’re kind of sketching out this new application that might have to consume some messages from our ERP system. That’s the system boundary. The system level diagram for this new application is going to be really, really simple.
We define two persons. And again, we’re using the C4 extensions defined by Simon Brown. There’s several supporters of Riccardo’s, one of those that has some extensions out there for pommel and you can call it PlantUML, or you can call it pommel. But we’re defining our extensions or defining the relationship between extensions. And that’s it. We just hit Alt-D and run the diagram. Easy as pie.
We can change the layout left to right and it just realigns and does its best to guess the direction of the versionable architect diagram. But that’s it for the system level.
OK, so now that we’ve done the system level, maybe we want to zoom in to how we’re going to structure this new application.
The Container Diagram
The next level is the container level in C4, the container diagram. So we have this new application. Let’s zoom in and try to figure out what is going to comprise that new application. We still have our ERP system, still have Twilio, still have the customer and the supplier.
Now we’re going to make the decision like, oh, maybe we’ll use Blazor Web Assembly as a client. Maybe we’ll use a .Net Core API running on the server. Or, maybe we’ll use a SQL Server database. So now we’re starting to define the architectural elements of how this new application is going to come to be. And in the same way, we just look at the text on the left and it is very, very straightforward. We have a key new level, which is the system boundary.
Within the system boundary, we’ve elevated one of our external systems to the system boundary. Then we have some containers for each piece that make up the new system and then relationships between them again, REL is short for relationships.
Going Deeper with your Diagram
So what do we need to dig in even more? We’re going to zoom in again and start defining maybe some patterns for how we’re going to implement Blazor, how we’re going to implement the logic on the back end in the .Net process that’s calling our database and running.
Here we can see that we’re describing a synchronous application bus. We have some command handlers, and we have some query handlers and those are talking to the database. Maybe one of the command handlers calls out to the SDK or the API of the Twilio service in order to send the text message. That’s great. Real clear level of understanding by this diagram for what we intend the structure of the code to come out to be. And in the text on the left, the definition of this diagram, again, is super straightforward.
We have a container boundary for the application, the .NET Core application that’s running on the server, and we’re breaking that up into components and relationships between it. Again, you can just define in text all of these symbols. If you are familiar with markdown for documents, it’s the same.
Summary: Versionable Architect Diagrams
So once again, to review, install a few dependencies via Chocolatey. These are the three things that we need for the VS code extension to be able to generate these diagrams. Alt-D is the hotkey in order to make the diagram pop up. Hold down the alt key and press D, and you can have system level diagrams and diagrams at various levels working for you.
Hope this helps. Happy diagramming!
Originally published October 29, 2020. Information refreshed April 20, 2022.
