Active Architecture – User Stories for Architecture

I had previously blogged about how I felt that “System User Stories” were required and filled an important gap. I now believe that extending User Stories to create these System User Stories is not the best solution.

I still believe that there is a gap in Agile techniques that needs to be addressed for certain types of applications. For simple CRUD applications it is very possible that you will not require these additional techniques. This discussion is meant to address those non-trivial CRUD applications. I think my error was in trying to extend the brilliant User Story concept to cover System Stories. I now see that it was a bit of a forced fit. What I would propose instead is something I refer to as Active Architecture documentation.

The argument for Active Architecture

Too frequently in Agile, the focus on Requirements is only on User Stories. Sometimes the focus is on User Stories and Technical Tasks, but not on any architecture or holistic system design requirements. While this may be acceptable for Web applications that are simple, trivial, and primarily event-driven, it certainly does not suffice for applications that may have complex back-end components such as:

  • Portfolio Rebalancing Engines
  • Payroll Engines
  • Network Optimization
  • Scheduling or Matching Engines
  • Really any application that has an engine. 🙂

Unfortunately, the amount of Architectural and Design Documentation has been greatly reduced by Agile due to the enormity of it and the waste. I agree 100% that there is waste, but I would suggest that the correct response was to create a new, leaner type of Architecture document. Instead of the traditional voluminous passive Architecture document, I recommend a new Active Architecture document that is composed of Component Conversations as illustrated below:

The issue with the traditional architecture documents are that they defined what the architecture was in a passive and distant way. Somewhat like a road map. What I am proposing is to define the architecture in an active way. Rather than just defining the map of roads, the documentation needs to define how the routes will be driven and in that active way, describe the road map. The traditional way of architecture documentation was too far removed from the actual act of system use to be relevant and effective. Architecture documents need to define what actions the architecture support, just like User stories did for user functions.

User stories capture interactions between the user and the system efficiently, and technical tasks capture lower level tasks that the system is required to do. But where in the Lean documentation do we define at a High level the interactions between system components?

The types of Agile Requirements I recommend are:

  1. User Stories – Stories of how the User interacts with the application or manual processes
  2. Component Conversations – Conversations between components of the application
  3. Technical Tasks – Technical tasks that the applications needs to perform within a component.

Creating these component conversations and thinking them through for the entire system will ensure the following:

  • That our User Stories are consistent in how functionality is handled across components
  • That our User Stories do not create an undue amount of rework when an original story is encountered in a later iteration
    • Ensures that the entire solution has been thought through at a high level
    • Reduces the chance that a story will be discovered late that will require earlier stories to be revisited
  • That our technical tasks are implemented consistently across components
  • They will define the complex back-end high level requirements that would be inefficient and possibly inconsistent to define on a story by story basis
  • They will define complex back-end high level requirements that may not be covered easily by user stories
  • Components conversations can be reviewed to ensure we have all the system functionality covered and there are no gaps.
    • Ideally in a graphical way

These Component Conversations define the Active Architecture of the solution. One possible format of the Components Conversations are: (and you can customize to fit your particular requirement)

[#][Component A] does [primary action].[object].[additional action] by [Action].[Component B] when [event]


I’ve used these component conversations on my current project and they have greatly improved the understanding for both myself and team members. It is crucial that these component conversations should not be very involved and take a long time. I time box of 1-2 days should be sufficient to ensure a consistent understanding of the system exists. The component conversations can then be modified and changed as we proceed through iterations. The focus should be on Lean and what is enough to provide the required value.

The concept has provided great value for my current project.