Service blueprints: creating a shared understanding of your architecture

architecture documentation   architecting   service blueprint  

---

Len Bass and colleagues at the Software Engineering Institute define software architecture as follows:

The software architecture of a computing system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and properties of both.

In other words, in order to reason about your application you need to understands its architecture. In particular, if you want to modernize a legacy application you need to understand its architecture as well as your target architecture.

In earlier articles OMG are you still using Rational Rose? and Using scenarios to reinvigorate your microservice architecture describe some key architecture and architecture documentation concepts.

In this article, I want to focus on describing the dynamic behavior of an architecture; connecting architectural elements to user; and describe what I think it is a valuable addition to an architect’s toolbox: service blueprints.

Documenting an architecture’s dynamic behavior is essential

As I described in Using scenarios to reinvigorate your microservice architecture it’s insufficient to merely describe the static structure of an architecture.structure. You must also describe its dynamic behavior, which is how architectural elements collaborate during a scenario.

The scenarios are the +1 of the classic 4+1 view model of software architecture.

There are a couple of different ways of visualizing a scenario including UML sequence diagrams and C4 dynamic diagrams. It’s important to remember that, as with architectural views, diagrams are necessary but often insufficient. You typically need text explaining each step in the scenario.

Scenarios connect architectural elements to requirements

Since the scenarios are derived from user stories, an additional benefit of using scenarios to document dynamic behavior is that connects the architectural elements to the requirements. Without these scenarios, you typically have a lifeless architecture that’s difficult to understand and discuss in a meaningful way.

Using service blueprints to connect architectural elements to users

Scenarios (sequence diagrams) are a good way to connect architectural elements to requirements. They are, however, rather technical and can be difficult for non-technical stakeholders to understand. Conversely, scenarios often don’t clearly communicate the complete user experience to technical stakeholders.

A really good way for all stakeholders to gain a shared understanding of both end-users and the application architecture is to use service blueprints. A service blueprint is a diagram that shows the interactions between the user, and the architectural elements. Here’s an example of a service blueprint (courtesy of Indu Alagarsamy - see below):

This service blueprint consists of three ‘layers’:

• Top - from left to right, are the user’s actions, which are part of a customer journey.
• Middle - below each user action are the architectural elements that support the action and the interactions between them.
• Bottom - alternative flows.

Some service blueprint might even have additional layers for humans, such as employees, and 3rd party applications.

A service blueprint is a fantastic, user centric view of an organization and its architecture that creates a shared understanding amongst all stakeholders. I think they are a great addition to an architect’s toolbox.

Learn more about service blueprints

If you want to learn more about service blueprints, my good friend Indu Alagarsamy is teaching a couple of workshops on service blueprints on November 15th at times that work well for all timezones.

Need help with accelerating software delivery?

I’m available to help your organization improve agility and competitiveness through better software architecture: training workshops, architecture reviews, etc.

Learn more about how I can help