I started working on an updated architecture diagram to illustrate the current state of my Blog Engine, and decided to write about the tools I use.

Why Keynote?

I am a big fan of Dot, a text-based language for making undirected and directed graphs using only text. Among other things, I’ve used Dot for generating Swift Package documentation with SourceDocs, or this diagram of Bobiverse (first book). Using text-based tools is great for source-control and versioning. Dot is capable of rendering really complex graphs (check their example gallery). However, Dot support for images is very limited, and creating (and reading) architecture diagrams is often much easier when vendor icons are used.

For this, I found Keynote the perfect tool. There are many online editors, and other native apps to make diagrams, but they often feel slow and clunky when compared. Besides, presentations are often a great way to share knowledge, whether this is on the web, at conferences, or at your workplace, sharing knowledge and ideas with other coworkers and/or teams. Being good at making presentations can take you far.

Presentation templates

Keynote, as well as Powerpoint and other slide editors, have a good list of presentation templates. Unless using a work template, I usually go with a bare one, picking either light or dark background.

Vendor icons

If you are working with Amazon Web Services, I highly recommend downloading their AWS Architecture Icons. I prefer downloading their PowerPoint toolkit, since it includes icons for all their services, well organized by category, but also other resources, like group and resource icons.

For other vendors, many companies have a Media or Brand page for press releases, with downloadable assets and instructions on how to use their logos. Here is the Media page for GitHub, for example. As you can see, if you clicked on the link, they provide downloadable versions of their main logos. However, other logos, like Github Actions, are missing. In this case, I often rely on searching online for their logos, trying to find a good transparent png image.

Let’s make a diagram

I started this article saying I was working on an updated version of an architecture diagram for my Blog Engine. Well, that was kind of a lie. I hadn’t started yet, so here we go. There is really not much to it, so I’ll focus on the key parts. If anything does not make sense, let me know on Twitter.

I’ll pick dark theme for this one.

Groups

My Blog Engine uses two GitHub repositories, the source and the destination (GitHub Pages site), a combination of Github Actions, and few AWS Services. For this, I’ll be using the group template from the AWS slides and define three groups.

Nodes

From the AWS toolkit, I’ll be using nodes for SQS Queue, SQS Message, AWS Lambda and S3 Bucket. The toolkit provides two different sets of icons, for services and for service resources. Choose whichever you feel looks better. For Github Actions, I downloaded a transparent PNG from the GitHub documentation site.

Webpage screenshots

Since both the source and destination are web pages, I like representing these with actual screenshots. In this case, I took a screenshot of this source GitHub Issue, and another screenshot of the destination article on my blog.

Connectors

Keynote has three types of line connector on the Shapes menu. However, the third one (the one that looks like a Bezier curve) is the only one that will actually snap to nodes and automatically adjust when the nodes are moved.

You can customize the connector by selecting a head stile (arrow) and the connection style (straight, curved, angled). It’s a good idea to also give some padding to the connector, so it doesn’t touch the nodes directly.

Final Diagram

Here is how my diagram turned out. Maybe too dark with the black background? Not sure. What do you think?

Some tips

• Make your nodes of the same kind have the same size. For example, all AWS Services should have the same size icon. If you use screenshots for webpages or mobile devices, keep their size consistent.
• Do your best to align your nodes in a grid pattern. This will make the diagram much easier to read.
• Use the same font size for node labels.
• Make your connections (arrows) consistent: same width, same head style, same color. In some cases you might want to use dashed or dotted arrows, to indicate different behavior. In my diagram, I used a dashed arrow for serving images from S3, because these are not copied to the GitHub Pages repo.

This article was written as an issue on my Blog repository on GitHub (see Issue #14)