application architecture   architecture documentation   architecting  

Understanding an architecture: part 2 - user stories and scenarios

This is part 2 in a series of article about understanding and documenting an architecture. The other articles in the series are:

In the previous article I described how I begin the process of understanding the architecture of a client’s application by learning about (and documenting) the system context. The system context describe the actors - humans and applications - that use the application to accomplish their goals and the external applications/services that are used by the application. The next step in the journey is to expand my understanding of actors’ goals by learning about the application’s key user stories and scenarios.

This article covers the following topics:

  • Understanding architecturally significant user stories
  • Understanding key scenarios
  • Using scenarios to animate the system context

Understanding architecturally significant user stories

A lot has been written about user stories so I’ll just make a few points. Briefly, a user story typically has the following format:

As <type of user>
I want <Some Goal>
So that <Some reason>

For example, one of the key user stories for the FTGO application is Place Order:

As a consumer
I want to place an order
So that I can eat

An application’s user stories are its functional requirements. But since the focus is architecture, I’m interested in the (typically) handful of stories that are either capture the ‘essence’ of the application and/or represent some form of technical risk/challenge. For instance, the FTGO application’s key user stories are those that describe what happens from when a user places an order to when its delivered by a courier.

Understanding key scenarios

User stories are intentionally high-level. Consequently, it’s valuable to understand and document key scenarios. A story’s scenario is a concrete example of a user attempting to accomplish the story’s goal. I prefer to write scenarios using the BDD Given-When-Then format.

For example, one scenario for the FTGO application’s Place Order story is:

Given a valid consumer
Given using a valid credit card
Given with a delivery address and time that is served by the restaurant
When the consumer places an order
Then an Order is created in the PENDING_ACCEPTANCE state
And the Consumer's credit card is authorized

Once again, the goal is to understand the key (architecturally significant) scenarios rather than every tiny requirement.

Scenarios are the key to understanding the architecture

Scenarios are more than requirements. They are also the key to understanding the architecture. That’s because you must understand/document the architecture’s dynamic behavior, which is how architectural elements interact during various scenarios. In other words, scenarios bring the static structure - the elements and relations - to life.

Using scenarios to animate the system context

For example, let’s look at using scenarios to understand the system context, which I described in the previous article. The elements of a system context view are the application, its actors and external application. While some scenarios only involve an actor and the application, more complex scenarios also involve external applications. It can be useful to document such scenarios.

For example, the participants of the Place Order scenario are the consumer, the FTGO application, and various external services, such as the Payment Service, and the Email Service. Here’s a sequence diagram that shows this scenario:

This sequence of events is as follows:

  1. The Consumer initiates checkout via the FTGO UI
  2. The FTGO application invokes the Payment Service to create a payment intent
  3. The FTGO UI displays the payment page
  4. The Consumer enters their credit card information
  5. The FTGO UI invokes the Payment Service to confirm the payment

In later articles, I use scenarios to animate the elements of other architectural views.

What’s next

In the next article, I explain the next step: understanding the system quality attributes, a.k.a. non-functional requirements.

Need help adopting microservices?

I provide consulting and training.

application architecture   architecture documentation   architecting  

Copyright © 2023 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.

Chris helps clients around the world adopt the microservice architecture through consulting engagements, and training workshops.

Remote consulting session

Got a specific microservice architecture-related question? For example:

  • Wondering whether your organization should adopt microservices?
  • Want to know how to migrate your monolith to microservices?
  • Facing a tricky microservice architecture design problem?

Consider signing up for a two hour, highly focussed, consulting session.

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 KGBJMRAM to sign up for $195 (valid until March 8th, 2023). There are deeper discounts for buying multiple seats.

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.

Learn more

Signup for the newsletter

LEARN about microservices

Chris offers numerous resources for learning the microservice architecture.

Training classes

Chris teaches comprehensive workshops, training classes and bootcamps for executives, architects and developers to help your organization use microservices effectively.

Avoid the pitfalls of adopting microservices and learn essential topics, such as service decomposition and design and how to refactor a monolith to microservices.

Delivered in-person and remotely.

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

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.

ASSESS your architecture

Assess your application's microservice architecture and identify what needs to be improved.

Consulting services

Engage Chris to conduct an architectural assessment.

Join the microservices google group


Note: tagging is work-in-process

anti-patterns   ·  application api   ·  application architecture   ·  architecting   ·  architecture documentation   ·  assemblage   ·  dark energy and dark matter   ·  deployment   ·  design-time coupling   ·  development   ·  devops   ·  docker   ·  glossary   ·  hexagonal architecture   ·  implementing commands   ·  implementing queries   ·  inter-service communication   ·  loose coupling   ·  microservice architecture   ·  microservice chassis   ·  microservices adoption   ·  microservicesio updates   ·  multi-architecture docker images   ·  observability   ·  pattern   ·  refactoring to microservices   ·  resilience   ·  sagas   ·  security   ·  service api   ·  service collaboration   ·  service design   ·  service discovery   ·  service granularity   ·  service template   ·  software delivery metrics   ·  success triangle   ·  team topologies   ·  transaction management   ·  transactional messaging

All content


24 Jul 2017 » Revised data patterns