Architect Tip: Versionable Architect Diagrams

Architect Tips

In this architect tip, we’re going to be talking about Versionable Architecture 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!

Having architecture diagrams that work for you as part of that. Now we want to have beautiful diagrams just like this one, but doing them in Visio, it just is 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 this method in a versionable fashion is to install a few chocolatey components. And it's really easy. You can download the files. If you've ever used chocolaty before, you just run these components, make sure you're in a power shell window that's running as an administrator. After that happens, you open up VS code and install the PlantUML extension.

We already have it installed here, so it's ready to go. And 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. Now, it starts with your development process. And 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; our 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 so we can do it in text. And this is that diagram in text and we're using the helpers the Azure plant, UML extensions and you can get those on GitHub.

We define an actor, which is a developer, and we just start using the symbols and their objects. And these are methods essentially. And so we're using the symbols were 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. And 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. And so the text on the left is translated easy, super easy versionable it's all text.

And so the next type of diagram is the system level diagram. 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. So we're kind of sketching out this new application that might have to consume some messages from our ERP system. OK, that's the system boundary. And so 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. And there's several supporters of Riccardo's, one of those that has some extensions out there for pommel and you can call it plantUML, 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 kind of realigns and does its best to guess the direction of the 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 next level is the container level in C4, the container diagram. So we have this new application. Let's zoom in and then we 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.

But 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. Maybe we'll use a SQL Server database. So we're 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 is very, very straightforward. We have a key new level, which is the system boundary.

And 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. 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.

So here we can see that we're describing a synchronous application bus and 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. And so 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, 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. And so, again, you can just define in text all of these symbols. And if you are familiar with markdown for documents, it's the same. 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!