Seeing the forest – with architecture visualization

In the last article, we introduced the Backstage System Model and System Archetypes, which help us understand the context of our integrations. But how do we bring this understanding to life? Architecture visualization!

C4 Model and Backstage System Model

One aspect of the Backstage System Model that the last article didn’t explore is the domain. Spotify defines a domain as “a high-level grouping of systems.” Domains help us understand how different integration systems relate to each other within a business context. For instance, a Retail domain might include a Product API and a Price API. While there may be no direct technical dependency between these systems, they are both parts of the organization’s retail offering.

domain
└── system
	├── components
	├── resources
	└── APIs

This hierarchal view of our architecture, from technical components up to the business domain, suits well with the C4 Model and its four abstraction levels: Context, Container, Components, and Code.

There is a good write-up of the C4 model from the Revision Team so I won’t get into any details on that.

The C4 levels don’t, however, align entirely with the Backstage Model with Domains, Systems, and Components, but Spotify has written a good post on how they adapted the C4 model to the Backstage System Model. They have redefined the core diagrams to three different levels:

• System landscape diagram: Describes a set of related systems, how they are connected, and what external systems they depend on — for example, all systems owned by a squad or all systems in a domain
  System context diagram: Describes how a system fits in the larger context of dependencies, dependents, and users
  System components diagram: Describes how one system is built up from individual components (known as container diagram in C4)

We use these three levels when we document our architecture.

• Level 0 provides a high-level overview of the systems within a specific domain and their dependencies. Unlike the C4 model’s Context level, which focuses on a single system, Level 0 captures the broader scope of a domain, offering insights into how systems collaborate within that context.
• Level 1 zooms in on a single system and its immediate dependencies. Note that this diagram does not include details not already in the Level 0 diagram. It focuses on a single system, which might give a better view when discussing a specific solution—level 1 matches ”Context” in the C4 Model.
• Level 2 dives into a system and shows its components, APIs, and resources—level 2 matches ”Container” in the C4 Model.

What about Components and Code? Since we tend to have small components, including them often doesn’t make sense.

To put everything into context (context is important, right?), here is an example from a Retail domain.

System Landscape

The System Landscape diagram shows all systems within the Retail domain and their external dependencies.

System Context

The System Context Diagram zooms in on one system and its direct dependencies. Note that there isn’t any new information in this diagram. It just focuses on a single system and its direct dependencies.

In this example, we zoomed in on the ”Electronic Shelf Labels Aggregator” system and showed how it integrates with its dependencies.

System Component

The System Component diagram zooms in, further showing the components of a system. In this example, we have zoomed in on the Electronic Shelf Label Aggregator System and can see that it consists of two components: one API and one resource (the queue).

Summary

In this article, we explored how to visualize our architectural landscape using a combination of the Backstage System Model and an adapted version of the C4 Model. We organize our systems hierarchically through domains (business groupings) down to individual components and document them across three levels: System Landscape (Level 0) for the broad system interactions within a domain, System Context (Level 1) for focused single-system views, and System Components (Level 2) for internal system structure. This approach allows us to effectively bridge the gap between business context and technical implementation while maintaining clear and helpful documentation at each level of abstraction.