Living systems blueprint

Imagine you're a new joiner in a corporate environment.

You are faced with a complex network of systems: databases, servers, platforms, logs, etc. They're all scattered around various wiki pages, chat messages, etc.

You have the challenge of trying to get your head across everything fast enough to be useful to the team.

You need a map of where to find everything.

When you get hit with a new code review, bug report, prod support ticket or just regular task, you need to quickly see a map of the whole ecosystem, locate the specific systems that matter for the problem at hand, and jump into them instantly.

This is not about conceptual or theoretical knowledge. It's about being able to actually navigate and access real, running systems.

Read actual logs
Query actual databases
Push actual code changes

Here is where a "living systems blueprint" might come in handy.

What it is

Borrowed from the service blueprint, famous in the world of UX design, this is a diagram of services.

Pull-quote: A service blueprint is a diagram that visualizes the relationships between different service components — people, props (physical or digital evidence), and processes — that are directly tied to touchpoints in a specific customer journey.

However, for our purposes as software engineers, it focusses on technical systems and services.

And it has an important additional feature: links. Crucially, you want this to be more than a diagram. It should link you to the real systems so you can actually ... you know ... do stuff!

You can create a diagram like this yourself, for your own use. Its sole purpose is to help you navigate your digital work environment. To diagrammatically represent all the important systems you might work with and how they connect to each-other.

Diagram format

Here's an example of such a diagram:

Notice the links. One click (or copy and paste into a tool) can take you directly to the system.

Say, to a CloudWatch log in Prod. Or a Postgres database in UAT. Or an API request in Postman.

Here is a breakdown of the elements of the diagram:

Components	Depicted by a rectangle	Components of the system, such as services, databases, log storage, blob storage, mobile apps, web front-ends and more.
Dependencies	Depicted by a line and arrow	Dependencies between components, so that one "depends upon" another, such as a service depending on a database.
Compositions	Depicted by a line and circle	Compositions of components, such as parent/child or container/contained.

Within each component rectangle, we have:

Icon	Quickly identify the type of the service.	Simple shape, such as a Material Design icon, or one of the standard vendor or cloud provider icons, say for AWS, Azure, Google Cloud, etc.
Title	Title of the service, as referenced in code, docs, etc.	Text in a larger font.
Type	Type of service. E.g. Web Service, Log, Database, Mobile App, etc.	Text in brackets, in a smaller font.
Links	Links to access the entity or related to the entity. For a web application, it might include links to environments. For a database, it might include links to a console or a URI that can be plugged into a database client.	Text with underlined links, in a smaller font.

Within the "Links" row, you might put links to the system itself, including multiple environments (also known as "stages") such as Development, Staging and Production.

Development | Staging | Production

Now imagine someone comes to you with the following request:

Help! Panic! I need to find out why Transfer from customer #098238 are failing in UAT!

You can check your living blueprint, locate the Transfer service, see that it's connected to the Transactions database and follow the link to the Console in UAT to query recent transactions.

How it helps

Of course, you probably won't need a diagram if you're working with only a small number of systems or services on a regular basis. Likely your brain has already memorized the systems and you have browser bookmarks and the like to navigate to them quickly.

But suppose you're working with many services (too many to memorize all their names), with non-trivial integration patterns, which you might need to access unexpectedly at a moment's notice. Then a living systems blueprint might help you out.

A living systems blueprint can serve as a form of Long Term Memory (LTM). Its spatial and connected form enables you to jump through a complex of network of interconnected systems and quickly locate just the resources you need via links, whether they are logs, consoles, dashboards, code files or anything else.

Systems blueprint sketches

Portions of systems blueprints can be split into "sketches".

You might want to do this if your main systems blueprint gets too crowded with components or if you want to depict a group of interrelated components on their own.

You could share a sketch with a colleague via a link, as part of a discussion in, say, a chat thread, pull request discussion thread or ticket comment thread.