/ Design

The Atomic Design System of Microservice Diagrams

Design systems are all the rage these days. Designers all around the world spend days on end discussing components, states and other ways of systematizing their design, so it's easy to use and quicker to implement.

In fact, I'm riding the wave as well. For a while now, I've been working on helping anynines, for whom I created logo and basic visual identity guidelines back in the day, systematize the entire product design and visual communication. Standard product design system is part of the equation, but since the company — outside of standard customer-facing products — also has a consulting arm, a large part of work is making sure that during the workshops, training courses and other events where developers are giving talks, the visual presentation is professional and consistent. Hence, I ended up designing an atomic design systems of diagrams.

The Business Case

Cloud infrastructure is a complex topic, which requires a whole lot of domain knowledge, so I ended up learning a whole lot about how the underpinning of the internet works. A good example is a difference between shared and dedicated service instances — when you get a dedicated service instance, it means that a virtual (or real life) machine is spawned running just your service instance, as opposed to shared instances, where one machine is running multiple service instances, which can lead to problems like competition for resources.

There are layers to this — for example, dedicated service instances (one instance per machine) might be clustered in one availability zone, making a local cluster. This cluster can be there replicated among multiple availability zones, for higher availability. If you wanted, you could also create multiple service instances running on a single virtual machine, but those machines are clustered in one availability zone. It's a complicated world.

Current Solution

Developers need to be able to create complex diagrams quickly, so they end up using a lot of different tools — from Draw.io to OmniGraffle. The language of choice seems to be a flavor of UML, a well understood, unified visual language of components that also happens to be taught at a lot of Computer Science courses as a weapon of choice.

The Problem With UML

The problem with most UML tools is that they're very basic and constrained to a set of very basic symbols, requiring people to get very creative to accomplish what they need to communicate. Most of them are also — quite frankly — ugly. To look more professional when talking to stakeholders, the team needed something more versatile and complete, with a designer available long term to help create additional symbols as they arise.

The Design Solution

After giving it some thought, I decided to work on creating a UML-esque component visual language, inspired partially by Atomic Design methods. First, we talked through smallest possible parts of the diagrams, designed them, and then started thinking about how they can work together. Hence, basic symbols for service instance (SI), virtual machine (VM) and availability zone (AZ) were born:

Figure 1: Basic symbols

Those symbols fit snuggly into each other, making it easy to illustrate codependence. If you need to draw multiple service instances running on a single virtual machine, you can. If you need to show a cluster of virtual machines running in one availability zone — piece of cake.

The thing that was still missing from the equation is state. All the pieces of this puzzle can be in multiple states, but we've decided to start with the most basic ones — available and working, disabled (for example turned off to save costs) and unavailable due to error. This would help easily illustrate and animate even as complex concepts as self-healing (replacing an erroneous instance with a newly spawned working one) or high availability (making sure the service is available even if one or more service instances has failed). Illustrated basic states ended up looking like this:

Figure 2: Symbol states

The rules are pretty simple. Enabled instance is full-color, disabled instance is semi-transparent, and failed instance is greyed out with an icon. That language can be easily applied to all basic symbols and scales well.

Secondary Symbols

On top of the basic symbols, I've also ended up designing a couple of helper symbols that were required to communicate the full picture, like worker instances (simple, small applications that are only supposed to do one thing well) and full-on application instances. That helped the developers create diagrams at any scale, aligned with branding and visual communication language, using the building blocks provided.

Figure 3: Helper symbols

The helper symbols were designed so they can also follow the enabled / disabled / failed convention.

Figure 4: Application states

Full Picture

On top of the rules listed above, we also ended up using size of the icon as a signifier of the plan chosen — small, medium, large. You can see an example of a chart designed using our new system below:

Figure 5: Example Diagram

Next Steps

Now that the design is done, the hard part begins — the people part of design systems. The challenge will be to communicate and enforce new standards across the team, which — as anyone who ever worked with developers knows — will not be easy. The idea is to make atomic symbols, as well as basic configurations (clusters, dedicated instances) available as SVG, so they're easy to use in any tool of choice, and possibly creating stencil sets for the most common tools.


As usual, if you have any feedback or ideas, or you need someone to help you solve your design problems in a systematic way, let's chat!