Spotify engineers recently published how they standardized architecture diagrams at the company. They defined a standard system model named the Spotify Software Model and adapted the C4 model to visualize it. This combination created a shared language used across the organization, which helps communication, aids decision-making, and supports Spotify's software's evolution.

Renato Kalman, senior engineer, and Johan Wallin, engineer at Spotify, explain the motivation for creating this framework:

Architectural diagrams are the bread and butter of software design and a foundational tool for communication and collaboration on software development. At Spotify, we have an incredibly complex network of thousands of interlinked software systems owned by hundreds of teams, so having a simple way to visualize these connections is essential. While capturing all of our software in one large diagram is technically possible, it would be very hard to understand and navigate. ​​We need tools to look at our architecture at different abstraction levels in order to make good design decisions and evolve our software in a sustainable way.

Spotify engineers store metadata about their software components in a software catalogue. To support standard architecture diagrams, they created the Spotify System Model, a set of core entities and abstractions that Spotify engineers can use to synthesize data about their software health, ownership, and dependencies. "We believe that a solid shared understanding and terminology around software and resources empower communication and collaboration, which is essential to success for a company at our scale," say Kalman and Wallin.

The C4 model is a lightweight graphical notation technique for modelling the architecture of software systems, created by Simon Brown. It is based on a structural decomposition of a system into containers and components. At Spotify, the engineers adopted the C4 notation and its best practices. However, they replaced its abstraction layer of contexts, containers and components with the Spotify System Model.

The C4 Model

Source: https://c4model.com/

Spotify uses Backstage to store the software catalogue metadata. Backstage is an open-source platform for building developer portals, driven by Spotify and is a CNCF incubation project. Using Backstage's extensibility, they created an Architecture plugin that generates C4 diagrams based on the Spotify System Model metadata stored in Backstage. Kalman and Wallin say that "having the system model available in Backstage has been very helpful for discovery purposes, understanding lifecycles, ownership, and relationships between software components, and automatically producing software visualization diagrams."

Several core entities make up the Spotify System Model. These include APIs representing boundaries between software components, Components representing individual pieces of software, and Resources that are infrastructure needed to operate components at runtime.

Relationship between core entities
Source:

https://engineering.atspotify.com/2022/07/software-visualization-challenge-accepted/

As their catalogue has grown, those components have become increasingly hard to understand, review, and relate to each other. As a result, they've introduced additional abstractions that help understand the broader software ecosystem. Systems are collections of entities that cooperate to perform some function, and Domains are a collection of Entities and Systems related to a part of the business.

A domain and a system in relation to core entities

Source: https://engineering.atspotify.com/2022/07/software-visualization-challenge-accepted