Show the Architecture from Different Views

It’s impossible to capture every interesting detail about the architecture in a single picture. Instead of trying to put everything into a single diagram, we’ll create multiple views of the architecture. A view is a story about the architecture told from the perspective of a particular stakeholder or set of related concerns.

Think about how we use a mapping application like Google Maps to plan a road trip. Zoom in and we can see city streets. Zoom out and whole cities become just dots along interstate highways. Apply an overlay and we can see real-time traffic or weather. We can even swap maps of streets for satellite images or topography. Some applications offer street-level perspectives, which allow us to see the world at eye level from a snapshot in time.

We can use these different views of the world in our mapping application to plan a road trip. What’s the best route from Pittsburgh to Albuquerque? How do we avoid that thunderstorm? Where is a good place to eat chicken chow mien along our route?

Just like a map, each view of the architecture helps stakeholders answer questions about the system. How is development progressing? Who is working on which components? How will we support our quality attribute scenarios?

There isn’t a fixed set of views for every software system, but there are several views that are useful for most software systems. Let’s explore some of these useful views in more detail.

Tell Us What Elements Do with an Element-Responsibility View

Lines and boxes are the architect’s most used tool and her least trustworthy companion. Box and line diagrams make complex relationships among elements easy to see, but their architectural meaning is never self-evident. Recall this overview diagram of the Project Lionheart services:

This diagram is missing vital information. We know every element serves a specific purpose, but a picture alone is not a view. The element-responsibility catalog shown for this diagram fills in the missing pieces. Depending on the information we need to share, we can express responsibilities as diagram annotations, in a table, or as descriptive prose.

Element-responsibility views are extremely common. In some cases, this might be the only view you need. If you can list the elements and their responsibilities, then you stand a chance of building a working system.

Zoom In or Out with a Refinement View

I always love that scene in a television crime show when the hero cracks the case by enhancing a blurry image. I can’t see his face. Zoom in. Enhance! The cool thing about software, unlike blurry images, is that we actually can zoom in and enhance nearly infinitely.

Refinement is the process of increasing detail in a model over a series of views. It’s like zooming in on a structure to show the elements’ inner workings, enhancing, and then zooming in again.

Let’s zoom into the Lionheart Display Business component to take a closer look at some of its static structures.

At one level of refinement, we can see the Display Business component uses a typical layered pattern: one layer for display, business, and service access logic, with a sidecar layer to organize data models and utility classes. This diagram establishes context, but we might learn more about maintainability if we refine further.

In this refinement, we show packages inside the layers and how they interact with one another so we can reason about maintainability quality attribute scenarios. Looking at this refinement, it’s clear that the RFP Package might be too interconnected, which makes testing and debugging difficult.

Notice that the Models and Utilities Layer is not shown in this refinement. Everything is allowed to use classes in the Models and Utilities Layer. Including all the relations would make the diagram too cluttered for analysis, so we eliminated some relations from this view. Slicing and dicing views is useful but can make the architecture models harder to understand.

Refinement views help us focus on the details needed to answer specific questions about the architecture. Coarse-grained refinements provide a big picture view of the world. After we’ve established the context, we can show finer-grained refinements by zooming in to show important details needed by specific stakeholders.

Use the principles of architecture minimalism described in ​Preserve Ambiguity​ to decide when to stop refining a model. Only refine to a level of detail necessary to demonstrate specific quality attributes and reduce high-priority risks.

Show How the Architecture Promotes Quality Attributes

A quality attribute view demonstrates how the architecture achieves specific quality attributes. Quality attribute views might hide details not relevant to the current discussion, or highlight details relevant only to the given quality attribute. For example, consider this availability scenario for Project Lionheart from the table.

A user searches for open RFPs and receives a list of available RFPs 99% of the time on average over the course of the year.

To satisfy this quality attribute, we introduced a redundancy pattern. Let’s create a view as shown in the figure.

Promoting availability means our Lionheart services must be resilient in the face of failures. To accomplish this, we’ll need multiple instances of the Display Business, Search Service, and Search Index components. Since the Display Business and Search Service components are stateless microservices, we can easily deploy multiple instances in any container management system such as Kubernetes^[16] or Marathon.^[17]

The Search Index is stateful and a potential performance bottleneck for our system, so we’ll need to be more careful about data storage. We’ll also need to think through routing when there is a fault to avoid downtime and data partitioning. To keep things simple, we’ll use a load balancer and Domain Name System (DNS) to route requests.

Let’s use the diagram to determine whether we satisfied the quality attribute scenario. Pretend one of the Search Index components fail. The load balancer detects the failure with a health check and routes requests to the secondary Search Index. So far, so good.

This view is moving in a good direction but needs more work. How often does the health check occur? What are the requirements for a ping? What happens if the load balancer goes down? What happens when a failed Search Index comes back online? These questions and more should be described in explanatory prose accompanying this diagram. One diagram might not be enough to thoroughly explain how the architecture satisfies our availability scenario.

Connect Elements from Different Views

With many views in play, it’s useful to see how elements in different views are related to one another. A mapping view serves just this purpose by combining two or more views into a new view that shows how the elements are related.

Two useful mapping views are work assignment and deployment. In a work assignment view, we show who works on different parts of the system by mapping teams with the elements they’ll build. Deployment views show where runtime elements from a component and connector view will be installed and used.

Here’s an example of a work assignment view for Project Lionheart:

Notice that this view is not a diagram. Our objective is to communicate design decisions by any means necessary. Sometimes a simple table is all that’s needed to get the job done.

Mappings create connections between stakeholders with different concerns. This work assignment view is perfect for a project manager who needs to create a schedule or staffing plan.

Mapping views provide a layer of context that can be difficult for stakeholders to piece together on their own. Consider a product manager’s needs. Maybe they want to know when certain features will be ready to ship. A mapping between architectural components and value-adding features would help everyone understand which parts of the software support different features. This tiny smidge of knowledge enables team self-organization and helps developers prioritize work with the product manager’s needs in mind. Now you’re empathizing with stakeholders!

Let Ideas Breathe with a Cartoon

All the views we’ve seen so far have been rather precise. Precision has a cost. Precise models require exacting details and are time-consuming to create. Sometimes precision gets in the way of communication, especially when you’re exploring ideas. As we’re getting to know the system, it’s sometimes useful to create accurate models with less precision.

An architecture cartoon is a fast-to-create, imprecise model that favors communication over analysis. Use cartoons for rapid iteration and informal communication. They are perfect for exploration workshops and impromptu discussions.

Cartoons capture the essence of the idea you want to share. Here is a cartoon of a horse and an anatomically precise diagram of a horse. A horse has four legs, a bushy tail, and a mane. A more precise drawing might help if we need details about the musculature or anatomy. But if we just need a placeholder for a horse, then my cartoon works fine.

Architecture cartoons use simple notations and ignore many of the best practices we’ll discuss throughout this chapter. Using loose notations is OK, especially while you’re working through an idea. Once design decisions start to converge, then it’s time to create a more precise model.

Bringing this back to architecture, here’s a cartoon of the Project Lionheart Overview. Compare it with the more precise views we’ve seen so far.

Create Custom Views to Show Exactly What You Need

Any view of the architecture that helps you effectively tell a story about the system to stakeholders is a view worth having. Get creative and make custom views for your particular purpose.

Views always combine multiple variables. Elements and responsibilities. Quality attributes and patterns. Elements and project schedules. Inventing a new view can be as simple as combining new variables with architectural elements. Need to show performance bottlenecks in the system? Start with a component diagram that shows information flow, color-code components based on execution time, and voilà, we’ve created a performance view.

Remember, all views, even custom views, are governed by an underlying meta-model as discussed in ​Design the Meta-Model​.