DEV Community: Simon Brown

Scripting support added to the Structurizr DSL

Simon Brown — Fri, 10 Sep 2021 16:10:41 +0000

The Structurizr DSL now provides a way to run scripts written in Groovy, Kotlin, Ruby, and JavaScript, via the new !script keyword. This gives you access to the underlying Structurizr for Java workspace, for when you need to do something not supported by the DSL.

For example, you could use a script to create the default set of views, without automatic layout enabled:

workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System"

        user -> softwareSystem "Uses"
    }

    !script groovy {
        workspace.views.createDefaultViews()
        workspace.views.views.each { it.disableAutomaticLayout() }
    }   

}

You could also use a script to programmatically add elements to a view, using more complicated logic than is possible via the DSL alone.

workspace {

    model {
        group "Group 1" {
            a = softwareSystem "A" {
                tags "Tag 1"
            }
            b = softwareSystem "B" {
                tags "Tag 2"
            }
        }
        group "Group 2" {
            c = softwareSystem "C" {
                tags "Tag 1"
            }
            d = softwareSystem "D" {
                tags "Tag 2"
            }
        }
    }

    views {
        systemLandscape "key" {
            !script groovy {
                view = workspace.views.getViewWithKey("key");
                workspace.model.softwareSystems.findAll { it.group == "Group 1" && it.hasTag("Tag 1") }.each{ view.add(it); };
            }

            autolayout
        }
    }

}

Scripting support is available now, via the open source Structurizr CLI and the free Structurizr Lite. See the Structurizr DSL language reference - Scripts and the Structurizr DSL cookbook - Scripts for more details.

Visualising ADRs

Simon Brown — Fri, 09 Jul 2021 12:14:52 +0000

I'm a big fan of architecture decision records (ADRs) - a collection of short text files, stored in version control, that provides a way to document the significant decisions made before/during the development of a software product. I highly recommend that all teams adopt this lightweight practice, and they are a core part of my minimal approach to software architecture documentation. For tooling, I really like Nat Pryce's adr-tools command line utility for managing ADRs.

Do team members ever look at that folder of ADRs though? And how easy is it to search for information related to a single decision, or perhaps even a chain of decisions? Something we could really do a better job of is visualising those decisions, making them easy to find and read.

Structurizr has supported publishing ADRs for a while now, and I've just added (an initial version of) a feature that visualises ADRs as a force-directed graph, showing the decisions and the connections between those decisions where they've been superseded. Here's a screenshot showing the decisions related to how the Structurizr cloud service has moved from Rackspace to Pivotal Web Services, and then onwards to Amazon Web Services.

If you have a folder of ADRs created using Nat's tool, you can get this visualisation for free with Structurizr Lite in under 5 minutes.

1. Create a workspace.dsl file

Create a file named workspace.dsl next to your folder of ADRs.

Add the following content to that file.

workspace {

  !adrs decisions

}

This says, "create a workspace, and load the ADRs from the decisions sub-directory".

2. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:

docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite

Be sure to replace PATH with the full path to the directory containing your workspace.dsl file.

3. Open Structurizr Lite

Open the workspace in a web browser by heading to http://localhost:8080 and you should see your decisions.

You can now click through the decisions, and press the Space key to open the quick navigation feature. Click the little graph button underneath the heading, and the visualisation will open.

Over time, the graph will start to change to reflect how decisions have been superseded, deprecated, etc.

Summary

As I said at the start, I'm a big fan of ADRs. Whether you're using Structurizr or building your own tooling, we can do better than keeping them hidden away in a folder.

Getting started with Structurizr Lite

Simon Brown — Wed, 23 Jun 2021 16:02:28 +0000

Structurizr Lite is a free version of Structurizr, packaged as a Docker container, and designed for developers who want to quickly author and/or view software architecture diagrams, documentation, and architecture decision records (ADRs). A software architecture model, views, and documentation (together called a "workspace") can be defined using the Structurizr DSL - what I referred to as Diagrams as code 2.0 in a previous post; a textual language specifically designed to support software architecture and the C4 model. Let's get started.

1. Create a new directory

First we need to create a directory somewhere to store our workspace.

2. Create a workspace.dsl file

Next we need to create a file called workspace.dsl inside that directory, with the following content.



workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System"

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}

You can find more about the Structurizr DSL at https://github.com/structurizr/dsl, but essentially this DSL file says:

Create a model with a user and a software system, where the user uses the software system.
Create a system context view for the software system, adding the default set of elements, using auto-layout.
Use the default theme for styling elements and relationships.

3. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:



docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite

Be sure to replace PATH with the full path to the directory created in step 1. For example, if the directory is located at /Users/alice/structurizr, the commands would be:



docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v /Users/alice/structurizr:/usr/local/structurizr structurizr/lite

4. View the diagram

Open the workspace in a web browser by heading to http://localhost:8080 and you should see your diagram.

If you make a change to the DSL file and save it, you should see that change immediately reflected when you refresh your web browser.

5. Add some documentation

Let's add some documentation to describe our software system. To do this, create a subdirectory named docs and create a file named 01-context.md inside that subdirectory, with the following content:



## Context

Here is a description of my software system...

![](embed:Diagram1)

Now change the content of the workspace.dsl file to be as follows (notice the addition of the !docs line):



workspace {

    model {
        user = person "User"
        softwareSystem = softwareSystem "Software System" {
            !docs docs
        }

        user -> softwareSystem "Uses"
    }

    views {
        systemContext softwareSystem "Diagram1" {
            include *
            autoLayout
        }

        theme default
    }

}

Save all files, refresh your web browser, and click on the top-left button with the icon that looks like a book. You should now see the Markdown documentation page that we just created, which itself is embedding our existing system context diagram.

Summary

Structurizr Lite provides a quick and free way to get started with the Structurizr tooling. It supports the full set of C4 model diagrams, along with the ability to publish Markdown/AsciiDoc documentation, and architecture decision records (ADRs). Enjoy!

Diagramming distributed architectures with the C4 model

Simon Brown — Wed, 19 May 2021 11:38:25 +0000

"I read that C4 is best suited for monolithic architectures and less suited to distributed architectures" ... this is a statement I see frequently, and it isn't true. The C4 model is a hierarchical collection of diagrams based upon a small set of abstractions. There's nothing here that makes it more or less suitable for distributed architectures than UML, ArchiMate, or ad hoc whiteboard sketches. The problem is really one of tooling, and our inability to think past static PNG files.

If you're following Conway's Law, and have different teams owning different parts of your distributed architecture, this post likely isn't for you. This post is really aimed at teams building a distributed monolith - one team, lots of separately deployable microservices and/or lambdas, lockstep deployment, etc. These architectures tend to have lots of elements and relationships at the C4 model container level, making it difficult to create a comprehensive container diagram that's not cluttered, and easy to understand. This tweet sums up the situation well.

"with serverless, you are deploying your UML collaboration diagram!"

Any diagram with 20+ elements (perhaps fewer) starts to get complicated quickly, making it harder to tell the story you want to tell. A complicated architecture will lead to a complicated diagram.

An example

This is an oversimplified example, (and please don't create a distributed architecture that's really just a fragile chain of synchronous services communicating with each other!), but I want to use this example to illustrate some points about diagramming. Many teams would initially approach this by drawing a diagram showing the entirety of their architecture - perhaps showing all of the containers that make up the software system, plus their external dependencies.

Granted this diagram isn't too bad, and this approach will work fine for smaller software systems. It falls apart very quickly once you start getting to 10 services, or 20 services, or 100 services. Although we'd ideally like to create a single diagram that shows everything, it's just not feasible in many cases. That approach to diagramming doesn't scale. You do have some options though.

Option 1: Create a number of smaller diagrams

One of those options is to create multiple diagrams showing a subset of the overall story. You could create diagrams to show a single domain, a bounded context, a business capability, a feature, and so on. Alternatively, you could create diagrams to focus on a single service plus its direct afferent/efferent couplings. Here's an example that focusses on "Service 1" rather than showing all containers.

We do lose some of the "big picture" by doing this, but this diagram is much easier to understand because it has a much more confined scope. A problem with this approach is the same one I outlined in Diagrams as code 2.0 ... we're going to need to repeat elements/relationships across multiple diagrams, and we need a strategy for keeping them all in sync when things change.

And that leads to tooling, and diagramming vs modelling. I've said this before: we need to stop using general purpose diagramming tools for software architecture diagrams (Visio, etc), and we should think carefully before handcrafting diagrams with PlantUML, C4-PlantUML, Mermaid, etc too.

The above diagram that focusses on "Service 1" is trivial to create with any "model + views" tooling. For example, with the Structurizr DSL, once you've defined your overall model, you can create the above diagram like this:



views {
  container softwareSystem {
    include user ->service1->
  }
}

This says, "create a container view showing the user, service 1, and anything directly connected to service 1". It's compatible with a number of diagramming formats too via the Structurizr CLI export command. Here's a PlantUML version of the above diagram, created from the same Structurizr DSL code.

A "model + views" tool provides a quick and easy way to tell different stories from the model, while keeping all resulting diagrams in sync. The Structurizr DSL and CLI are free and open source, plus any good UML tool from the past 20+ years should offer this functionality too, albeit with a very different user experience. Modelling is not new, and we really shouldn't have thrown it away in our haste to become "agile".

Option 2: Use a different visualisation format

With all the computing power available to us, it still amazes me that teams "just want a PNG image to embed in Confluence". Other documentation tools are available, of course.

Traditional static diagrams are fabulous for communication, but they should not be the only tools in your toolbox. Once you relinquish your obsession with static PNG images and jump across the chasm, you might find there are other visualisation formats that are more suited to helping you tell a story.

For example, an interactive force-directed graph is better suited to showing and exploring larger quantities of data. Something like D3.js admittedly has a steep learning curve, but makes this relatively straightforward.

(yes, the irony of posting a static screenshot of an interactive graph is not lost on me, so here's a link to the interactive version)

Alternatively, there are tools like Ilograph, which provides a way to navigate a model using an interactive UI.

(a Structurizr DSL to Ilograph export is available if you don't like writing Ilograph's YAML definition by hand)

Summary

In summary, the C4 model is not less suitable than any of the other alternatives for diagramming distributed architectures. And you have the same set of problems diagramming the components inside a larger monolithic application too. Those problems are related to the size and complexity of the diagram. If a diagram with a dozen boxes is hard to understand, don't draw a diagram with a dozen boxes!

Instead, switch from diagramming to modelling, think about what the story is you're trying to tell, and look at how technology can help you achieve that goal. Diagrams as code 2.0 is a very powerful approach if you're willing to jump across the chasm away from diagramming.

Diagrams as code 2.0

Simon Brown — Thu, 13 May 2021 13:34:33 +0000

Diagrams as code is becoming a popular way to diagram software architecture, particularly for long-lived high-level documentation. You write the diagram source in a text-based domain specific language (e.g. PlantUML, C4-PlantUML, Mermaid, WebSequenceDiagrams, Graphviz/DOT) or a programming language (e.g. Diagrams), and render diagrams using web-based or command line tooling. The benefits are well understood - writing the diagram source as text allows for easy integration into software development practices and toolchains, plus the automatic layout facilities allow authors to focus on content.

But there's a problem with this approach, which I'm going to call "diagrams as code 1.0" - if you need to create multiple diagrams, you need to create multiple diagram source files, and ensure that you keep these files in sync.

Some tools do provide a way to "include" snippets, but most don't, forcing you to repeat information across those diagram definitions. Once you violate the "DRY principle", you need to ensure that any changes you make to one diagram are reflected elsewhere. Easy in theory ("we'll just use global search and replace", etc), but that doesn't necessarily happen in the real world.

One way to resolve this problem is to generate multiple diagrams from a single source file. To do that, we need to shift our thinking away from "diagrams", and towards "views of a model". That's the essence of "diagrams as code 2.0" - it's a way to define a model of our software architecture and the views that we'd like to see, ultimately resulting in a consistent set of diagrams that are generated for us.

This is the concept implemented by the Structurizr tooling, the majority of which is open source. Structurizr builds upon "diagrams as code", providing a way to create multiple diagrams from a single model, using a number of tools and programming languages. There are three key concepts:

Workspace - this is the definition of the model and views, described using an open JSON format.
Authoring tools - these provide a way to create a workspace. The most popular is the text-based Structurizr DSL.
Rendering tools - these provide a way to render the views as diagrams. Supported diagram formats include PlantUML, C4-PlantUML, Mermaid, DOT, WebSequenceDiagrams, Ilograph, and the Structurizr cloud service/on-premises installation.

The separation of authoring and rendering reduces lock-in to any particular diagramming tool. And having a model of your software architecture provides a way to slice and dice it to create many different views, which can then be rendered using the best tool for the task ... a static PNG, an interactive and zoomable SVG, or perhaps an interactive force-directed graph.

Summary

To summarise the key differences:

Diagrams as code 1.0: you write diagram definitions by hand
Diagrams as code 2.0: diagram definitions are generated automatically, by tooling, based upon views of a model

Although many teams define their models by hand, there's nothing preventing you from generating the model automatically, in part or in whole, by parsing infrastructure as code definitions, parsing distributed log files, performing static analysis of a code base, etc. Such techniques are especially useful for teams seeking ways to diagram their larger and more complicated distributed architectures.

Structurizr quick tip: moving relationship descriptions

Simon Brown — Thu, 28 Jan 2021 17:36:19 +0000

By default, Structurizr will render relationship descriptions half way along the line, like this:

If you need to move the relationship (perhaps because it's overlapping something else), when editing the diagram, you can hover the mouse pointer over the relationship so that it's highlighted, and press the Up/Down cursor keys to move it forwards/backwards along the line.

Just note that this doesn't work when auto-layout mode is enabled.

Structurizr quick tip: hiding descriptions

Simon Brown — Wed, 27 Jan 2021 07:57:49 +0000

By default, Structurizr will include an element's descriptive text inside of that element when rendering a diagram:

While that level of information definitely enriches the diagram, there are situations where you might not want to show the descriptive text, for example if you're doing a presentation. For this reason, Structurizr allows you to hide the descriptive text in a couple of ways.

When you're viewing a diagram, pressing the d key will toggle the descriptions on and off:

If you'd like to hide the descriptions a little more permanently, you can use a style for the Element tag, setting the description property to false. For example, with the Structurizr DSL:

styles {
  element "Element" {
    description false
  }
  ...
}

As a bonus tip, you can also increase the font size in a similar way, to enlarge the text for presentation purposes:

Summary

The descriptive text can be useful, but sometimes you don't need to see it. Structurizr makes it easy to show/hide element descriptions, without needing to modify your diagram.

software-architektur.tv

Simon Brown — Fri, 22 Jan 2021 16:24:17 +0000

Earlier today I had the pleasure of chatting to Eberhard Wolff about all things software architecture related ... architecture and agile, the role, whether architects should write code, UML, the C4 model, and Structurizr. If you missed it, here's a recording of the live stream.

Modelling multiple relationships

Simon Brown — Fri, 20 Nov 2020 08:15:05 +0000

The topic of how to model multiple relationships between the same two elements has come up a number of times this week, so here's a quick tip.

To explain the situation, imagine you have an online book store that has customers. Those customers can do a number of things; make purchases, make pre-orders, browse, search, view their previous orders, and so on. To describe this with a diagram, many people would simply draw two boxes, and have one arrow per major use case/feature/story/etc. That would look something like this.

While correct and accurate, this approach tends to clutter the diagram, and each time you add a new major feature, you need to add another arrow.

A better way to think about this is that there's a single relationship between the customer and the online book store. Perhaps the customer "uses" the online book store or, to be more descriptive, perhaps the customer "browses and makes purchases using" the online book store.

If you do want to show each of the major use cases/features/stories/etc and how they work at runtime, you can do that with a unique dynamic diagram for each of those use cases/features/stories. With this approach, essentially what you have is a single relationship in the static model, with each dynamic diagram showing an instance of that relationship.

I hope that helps!

Diagrams as code

Simon Brown — Wed, 28 Oct 2020 16:45:49 +0000

The technique of "diagrams as code" just appeared on the ThoughtWorks Tech Radar (as "Trial"), with the Structurizr DSL also getting a mention.

Diagrams as what?

Like "infrastructure as code", "diagrams as code" is a bit misleading to be honest, as it seems to be used as an umbrella term for ways to create diagrams using a text-based approach. Some tools use real code, and others use a text-based DSL. Just bear that in mind when choosing your tooling. Whichever language you choose, everybody on your team will need to learn it in order to create diagrams.

The benefits of "diagrams as code"

Visio, draw.io, LucidChart, Gliffy, etc - not recommended for software architecture diagrams covers my thoughts on why we can do better for software architecture diagrams, and "diagrams as code" is certainly a step in the right direction. The most obvious benefits are the ability to use the text-oriented tooling we already use as software developers, text is easily version controllable and diff'able, plus many of the "diagrams as code" tools can be scripted and integrated into a build pipeline for automatic documentation generation.

Diagrams vs models

And that's a good step forward from tools like Visio, but it really only scratches the surface of what's possible. Most "diagrams as code" tooling provides a way to create a single diagram from a single textual source file. So if you need to create two related diagrams, you'll need two separate source files. Some tools do provide a way to share common snippets via "includes", but generally you have to ensure that you keep both source files in sync when you make a change to either of them. Modelling software architecture with PlantUML shows an example of this, and presents a solution in the form of the Structurizr DSL.

The Structurizr DSL is an open source project that I built during the depths of the COVID-19 lockdown earlier this year. It's a textual domain specific language for defining a software architecture model (based upon the C4 model), and essentially just a thin wrapper around the existing open source Structurizr for Java library. The first version of the DSL only took a week to build!

The Structurizr DSL is actually much more powerful than the other tools it's compared to, because it allows you to define a collection of elements/relationships (a "model"), and multiple views of those elements/relationships. This model-based approach allows you to share elements/relationships across diagrams, keeping everything in sync when you make changes. This is a very powerful concept, especially when coupled with the next thing I want to mention.

Multiple output formats

Most of the "diagrams as code" tools you'll see today are focussed on creating diagrams in one output format, via one input format. If you define a diagram using the PlantUML diagram syntax, you'll need PlantUML to render that. The same is true for Mermaid, WebSequenceDiagrams, and the Python-based "Diagrams" tool. Use those input formats and you're locked into using those tools to render your diagrams.

The Structurizr DSL is very different. The text-based DSL used to define a model and views is tooling agnostic, and the open source Structurizr CLI provides a way to render those views as diagrams using a number of tools; including the Structurizr web renderer, PlantUML, Mermaid, WebSequenceDiagrams, and Ilograph. Each rendering tool provides something slightly different, so the Structurizr DSL is a fantastic way to try a number of diagramming tools without being locked in to any of them. Getting started with the Structurizr CLI shows this in action.

Humans vs computers

One of the assumptions most people make about "diagrams as code" is that these text-based diagram (or model) definitions are authored by humans. And that's how the majority of teams use these tools at the moment. But, again, we're only scratching the surface of what's possible here. Rather than writing the code/text yourself, what if a computer was to do this for you? Perhaps it could parse your AWS CloudFormation definitions, and automatically generate your cloud architecture diagrams via PlantUML, Mermaid, or the Structurizr DSL.

There isn't much tooling available to support this type of use case yet, but as adoption of "diagrams as code" increases, I'm certain we'll be asking tools to do the hard work for us. It'll be interesting to see how this space evolves over the next few years.

Summary

I've been advocating "diagrams as code" since the I released the initial Structurizr for Java library back in 2014, so it's great to see the general concept appear on the ThoughtWorks Tech Radar. I've certainly seen many of the organisations that I work with either adopt this already, or they're looking at better approaches to creating long-lived documentation. "Diagrams as code" is definitely worth trialling if you've not looked at it yet, and the Structurizr DSL demo is a great way to get started.

Cloud architecture diagrams

Simon Brown — Thu, 08 Oct 2020 21:04:47 +0000

I've seen a lot of discussion about cloud architecture diagrams recently, with people specifically asking how to create them, which tools to use, and where to get the icon sets. Many of the example cloud architecture diagrams that I see online are relatively generic, and look something like this.

This diagram shows that a number of AWS services are being used; including Route 53, Elastic Load Balancer, EC2 (with auto-scaling), and MySQL on RDS. It looks good, it's colourful, and it uses the appropriate icons from the AWS icon set. It's a decent first attempt because it helps to highlight which AWS services are in use. But that's also the biggest problem - it's an "infrastructure diagram", and is only telling you half of the story. Understanding which AWS services are being used is great, but I'd really like to also know how you are using them.

Deployment diagrams

Most software development teams would be better creating a "deployment diagram", which shows the mapping of deployable things (e.g. your applications and data stores) to things that exist in the infrastructure environment. UML has a deployment diagram, which allows you to show the mapping of deployable artifacts onto device nodes and execution environments. The C4 model also has a deployment diagram, which shows the mapping of C4 model containers (again, applications and data stores) onto things that exist in the infrastructure environment (which I call "deployment nodes"). Here's an example.

This diagram again shows the AWS services in use, but it also shows what they are being used for, through the inclusion of the web application and database. You can, of course, add more detail as needed; including VPCs, VLANs, firewalls, IP addresses, instance counts, scaling limits, etc. It's worth noting that the same advice applies to diagramming Docker and Kubernetes environments too - remember to show your own applications and data stores.

Summary

Many of the example cloud architecture diagrams you'll see online are good starting points but they only tell half of the story. To tell more of the story, favour deployment diagrams over infrastructure diagrams.

How to review a software architecture diagram

Simon Brown — Mon, 27 Jul 2020 11:02:44 +0000

I see hundreds of software architecture diagrams every year, predominantly through my software architecture workshops. Some diagrams are better than others, but I've noticed that many people struggle to critique a diagram because they're not really sure what to look for. So that's the purpose of this blog post. Let's start with a fairly typical example of a whiteboard diagram from one of my workshops.

On the face of it, this diagram doesn't look too bad. It's high-level, clean, concise, colourful, and you might even be able to work out what's being described here. But we need to look a little closer.

General aspects

Let's start by looking at the diagram as a whole. Here are a few initial things to think about:

Does the diagram have a title?
Do you understand what the diagram type is?
Do you understand what the diagram scope is?
Does the diagram have a key/legend?

I'd estimate that upwards of 90% of the initial diagrams I see created during my workshops don't have a title! In this case, the diagram does have a title of "Context", but it's not explicit about what it's showing the context of, and what the diagram scope is. My assumption is that the large box labelled "Risk System" is the scope of the diagram, but a better title would clarify this.

And regarding notation. Well, this looks like an ad hoc collection of "boxes and lines" rather than being UML or ArchiMate. And while that's not necessarily a bad thing, a diagram key/legend would help readers to understand the notation being used. I'd recommend adding a diagram key/legend for UML and ArchiMate diagrams too, since not everybody will know these visual languages.

Elements (boxes)

Let's move on to look at the elements in more detail. Again, here are some things to think about:

Does every element have a name?
Do you understand the type of every element? (i.e. the level of abstraction; e.g. software system, container, etc)
Do you understand what every element does?
Where applicable, do you understand the technology choices associated with every element?
Do you understand the meaning of all acronyms and abbreviations used?
Do you understand the meaning of all colours used?
Do you understand the meaning of all shapes used?
Do you understand the meaning of all icons used?
Do you understand the meaning of all border styles used? (e.g. solid, dashed, etc)
Do you understand the meaning of all element sizes used? (e.g. small vs large boxes)

Every element has a name here, so that's good, but some of those names are acronyms/abbreviations. I know what "RDS" means here, but you probably don't, so that should really be fixed. "IAM" is quite a generic term too, so perhaps it would be better to add more detail. We have a collection of shapes being used here, and I'm not sure what the difference between the rectangles and the ellipses is. It's the same story with colour. Why are some elements blue, while some are black?

Moving away from the visual aspects, it's not actually clear what the elements represent, in terms of the level of abstraction. Are they all the same thing (e.g. "software systems"), or are some of them (e.g. the "Audit Log") really just an implementation detail of the "Risk System"?

Relationships (lines)

Finally, let's look at the relationships:

Does every line have a label describing the intent of that relationship?
Where applicable, do you understand the technology choices associated with every relationship? (e.g. protocols for inter-process communication)
Do you understand the meaning of all acronyms and abbreviations used?
Do you understand the meaning of all colours used?
Do you understand the meaning of all arrow heads used?
Do you understand the meaning of all line styles used? (e.g. solid, dashed, etc)

Only around half of the lines are labelled, and this is very common. I imagine that "audit logs" are being sent to the "Audit Log" box, but it would be nice to know what sort of things this might include. And "input" (from "RDS" to "Risk System") is quite generic and ambiguous, especially if you don't know what "RDS" means.

While most of the arrows are unidirectional (one-way), there's a bidirectional (two-way) arrow between the "Risk System" and "IAM" boxes. I'm not a fan of bidirectional arrows, because they tend to be harder to label correctly.

A better diagram

I've seen a number of "diagramming anti-patterns" blog posts in the past that will show you the problems associated with poor diagrams, but fail to show you the "good" example. So let's do that.

Here's a better version of the diagram above. I've used a tool for this (diagram source), but you could use a whiteboard or sheet of paper.

I've made a few assumptions about the audit log, data retention, and logger elements being implementation details, so I've omitted them from this System Context diagram. Every element has a name and description, plus I've also included some text inside the element to explicitly state what type of thing the element represents (i.e. "Person" or "Software System"). All lines are labelled too. Finally, there's a diagram key that shows the different shapes and colours being used.

Summary

Learning how to review a software architecture diagram is a relatively easy skill to pick up, and I'd recommend using my diagram review checklist the next time you need to do a review.

From a tooling perspective, sticky notes on a whiteboard work really well, but if you need something online, take a look at the Structurizr diagram review tool, which you can use for free. Alternatives include collaboration tools like Miro and Mural.

Creating good software architecture diagrams is a huge topic, but if you're interested in learning more, I'd recommend starting with the C4 model.