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
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
Here’s a sequence diagram that shows this scenario:
This sequence of events is as follows:
Consumerinitiates checkout via the
FTGO applicationinvokes the
Payment Serviceto create a payment intent
FTGO UIdisplays the payment page
Consumerenters their credit card information
FTGO UIinvokes the
Payment Serviceto confirm the payment
In later articles, I use scenarios to animate the elements of other architectural views.
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.