One Model to Draw Them All

Architecture diagrams are the universal shorthand of software teams — a handful of boxes and arrows can convey more about a system's design than pages of prose. But at Spotify's scale, with thousands of interconnected services owned by hundreds of teams, that shorthand breaks down. A single diagram capturing everything would be technically possible yet practically useless to navigate.

The challenge is one of abstraction. Teams need to view the same architecture at different levels of granularity, from a single component to an entire business domain, without losing meaning or context. Spotify's answer has been to build a shared vocabulary for describing software architecture, then to couple it with automated diagram rendering that stays in sync with actual system metadata.

A Standard Vocabulary for Software

To reason about its sprawling ecosystem, Spotify established a system model — a formalized set of entity types that form the basis for its software catalog. Three core entities describe the building blocks:

  • APIs: the boundaries between components, defining interfaces for interaction
  • Components: individual pieces of software, from backend services and websites to data pipelines and libraries
  • Resources: runtime infrastructure such as databases, virtual machines, and storage buckets

Figure 1. Relationship between core entities .

Two higher-order abstractions group these entities into meaningful units: Systems, collections of entities that work together to perform a function, and Domains, which tie entities and systems to parts of the business. Expressing this model as metadata is what makes an automated, searchable software catalog possible — one that tracks ownership, dependencies, and lifecycles across the company.

Beyond the Whiteboard

Spotify's engineers have long relied on whiteboard sketches to map out system interactions. Those diagrams work well for a small group in a room, but they don't travel, and they don't scale to a distributed workforce. Digital drawing tools solved the portability problem but didn't address the deeper ambiguity: what does each box represent? Does an arrow mean a dependency or just data flow? Without a convention, every diagram requires an interpreter.

The team evaluated formal standards like UML but found them too heavy for everyday communication. Instead, they adopted the C4 model, which provides a set of abstractions and a standard notation for drawing software diagrams. C4 occupies the middle ground between ad-hoc sketches and rigid formalism — it guarantees that a diagram can stand alone without external context.

Rather than layering two separate abstraction schemes, Spotify kept C4's notation and best practices but swapped its standard abstraction layer for the Spotify System Model. That led to a new set of core diagram types tailored to the organization:

  • System landscape diagram: shows how a defined set of systems connect to each other and to external dependencies, such as all systems within a squad or domain
  • System context diagram: places a single system in its broader environment of users, dependencies, and dependents
  • System components diagram: breaks down one system into its constituent components, analogous to a C4 container diagram

Figure 3. Spotify diagrams compared to C4 diagrams, based on an image from c4model.com. C4model.com is owned by Simon Brown; for website licensing information click on the image

The payoff comes from automation. Because these diagrams render directly from metadata in the software catalog, they are always current with the system's intended design as recorded there. No more wondering whether a hand-drawn chart reflects the current state. An Architecture tab in the Backstage plugin system surfaces a component diagram on each system page, with external entities linked to their own diagrams for seamless interactive navigation.

Shared Language, Clearer Design

Adopting a unified notation has ripple effects beyond documentation. Teams can now draft designs for new systems, or plan changes to existing ones, in a universal language that their colleagues across the company understand immediately. That consistency has measurably improved cross-team collaboration and made onboarding easier — new hires and external stakeholders can traverse the architecture interactively, following links and understanding how systems fit together.

The aggregated view also surfaces patterns that are invisible at the component level. Recurring designs, accumulated technical debt, and structural vulnerabilities become easier to spot when large numbers of systems are rendered in a consistent format.

Practical Advice for Adopting a Model

For organizations struggling with complexity, the path Spotify took is repeatable. Start by acknowledging that an abstraction model is a prerequisite; without one, diagrams will always be ambiguous and projects will struggle with inconsistent mental models. A framework like C4 works as a strong foundation, and Spotify's own system model demonstrates how an organization might tailor abstractions to its own architecture.

Standard notation is the second pillar. Adopting C4 or at least borrowing from its conventions ensures your diagrams are consumable with minimal context. The final step is automation, which requires a software catalog driven by metadata. That investment pays off not only in diagrams that never go stale, but in better insight for planning and operating software at scale.