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

architecture documentation   architecting   service blueprint  

Copyright © 2024 Chris Richardson • All rights reserved • Supported by Kong.

About is brought to you by Chris Richardson. Experienced software architect, author of POJOs in Action, the creator of the original, and the author of Microservices patterns.

New workshop: Architecting for fast, sustainable flow

Enabling DevOps and Team Topologies thru architecture

DevOps and Team topologies are vital for delivering the fast flow of changes that modern businesses need.

But they are insufficient. You also need an application architecture that supports fast, sustainable flow.

Learn more and register for my June 2024 online workshops....


I help organizations improve agility and competitiveness through better software architecture.

Learn more about my consulting engagements, and training workshops.

LEARN about microservices

Chris offers numerous other resources for learning the microservice architecture.

Get the book: Microservices Patterns

Read Chris Richardson's book:

Example microservices applications

Want to see an example? Check out Chris Richardson's example applications. See code

Virtual bootcamp: Distributed data patterns in a microservice architecture

My virtual bootcamp, distributed data patterns in a microservice architecture, is now open for enrollment!

It covers the key distributed data management patterns including Saga, API Composition, and CQRS.

It consists of video lectures, code labs, and a weekly ask-me-anything video conference repeated in multiple timezones.

The regular price is $395/person but use coupon ILFJODYS to sign up for $95 (valid until April 12, 2024). There are deeper discounts for buying multiple seats.

Learn more

Learn how to create a service template and microservice chassis

Take a look at my Manning LiveProject that teaches you how to develop a service template and microservice chassis.

Signup for the newsletter

BUILD microservices

Ready to start using the microservice architecture?

Consulting services

Engage Chris to create a microservices adoption roadmap and help you define your microservice architecture,

The Eventuate platform

Use the platform to tackle distributed data management challenges in your microservices architecture.

Eventuate is Chris's latest startup. It makes it easy to use the Saga pattern to manage transactions and the CQRS pattern to implement queries.

Join the microservices google group