Architectural Envisioning on Agile Projects


One of the common misperceptions with agile software development is that agilists don't "do architecture." This completely ignores the 11th principle of the Agile Manifesto which states that the best architectures evolve over time. In this article Scott Ambler overviews an agile practice called "architecture envisioning" which enables you to gain the value from modeling without the cost of needless documentation.

One of the common misperceptions with agile software development is that agilists don't "do architecture." This completely ignores the 11th principle of the Agile Manifesto which states that the best architectures evolve over time. More importantly, when you observe agile teams in action, you find that the majority of them do some initial architecture modeling at the beginning of the project. But, perhaps because agilists are not creating detailed architectural specifications as the result of a "big design up front" (BDUF) approach, many people think that we're not doing architecture. Nothing can be further from the truth, and in this article I overview an agile practice called "architecture envisioning" which enables you to gain the value from modeling without the cost of needless documentation.

Agile Model Driven Development (AMDD) explicitly includes an initial requirements and architectural modeling effort during Iteration 0 of an agile project (see Figure 1).[i] Iteration 0 has various names, for example Eclipse Way calls this the Warm-Up phase and Open Unified Process (OpenUP) calls it the Inception phase. The basic concept is that this is the period of the project where you try to get the project off on the right foot. Your goal is to understand the scope of the effort and to identify a plausible technical strategy. The information garnered from these efforts will help you to do initial high-level estimating and scheduling, which in turn enables you to gain funding and support for your project. Before you say that Agilists don't work this way, note that the DDJ 2007 Agile adoption survey found that 77% of agile were doing initial high-level agile architecture modeling, and that 88% of those teams found the effort worthwhile.[ii] 


Figure 1. Agile Model Driven Development (AMDD) Lifecycle


Figure 1 also shows that you model, on a just in time (JIT) basis, throughout construction iterations. At the beginning of each iteration you'll do some modeling as part of your iteration planning efforts where you determine what you're going to do and how you think you're going to do it. You'll also "model storm" regularly. A model storming session is an impromptu event where you model with one or more people to explore a feature or to think through the high-level design strategy to implement a feature. Most agile teams will specify the requirements and design detail via a test-driven design (TDD) approach in the form of tests, which in effect are executable specifications.

With architectural envisioning you perform some high-level architectural modeling early in the project to help foster agreement regarding your technical strategy within the team and with critical stakeholders. The goal at this point is to identify an architectural strategy, not write mounds of documentation, enabling you to do this swiftly. The secret is to keep things simple. You don't need to model a lot of detail, you simply need to model enough. If you're writing use cases this may mean that point-form notes are good enough. If you're domain modeling a whiteboard sketch or collection of CRC cards is likely good enough. For your technical architecture a whiteboard sketch overviewing how the system will be built end-to-end is good enough. I cannot say this enough: your goal is to build a shared understanding, it isn't to write detailed documentation.

What Models Should You Create?

When you're initially envisioning the architecture you'll typically focus on a few high-level free-form diagrams which overview how you think you'll build the system. When envisioning the architecture for a business application, you should consider creating:

  1. A technology diagram. Often some form of technology stack diagram or UML deployment diagram will do. These diagrams are useful because they depict the major software and hardware components, including legacy systems and databases that you'll need to access, and how your system will potentially interact with them. Your goal should be to identify these assets and discuss their viability as sources of functionality and/or data for your system.
  2. A user interface (UI) flow diagram. Another common diagram to create is a UI flow diagram, also called a UI navigation diagram or UI wire frame, to explore how you will architect the UI of your system by exploring the flow between major screens/pages and reports. If you do not architect the user interface effectively you run the risk that you will build a system that your stakeholders aren't interested in working with. Remember, the UI is the system to your end users.
  3. A domain diagram. Part of your initial architectural modeling efforts should include the development of high-level domain model.[iii] This model should be very slim, capturing the main business entities and the relationships between them. Some people consider domain models to be a requirements model instead of an architecture model, but as you see in Figure 1 both of these initial modeling efforts are performed in parallel so how you categorize the model doesn't matter much in practice.
  4. Change cases. Change cases are architecture-level requirements which describe a potential technology or business change which your system may need to support in the future. Change cases allow you to consider the long-term viability of your architecture without requiring you to overbuild your system because you can think through the impact of likely changes to ensure yourself that your system will still work.

Your architecture models will evolve throughout your project, and the diagrams will often form the basis of your system overview documentation that you write towards the end of the lifecycle. Because you know that these models will evolve there really isn't much pressure to get them "perfectly correct" early in the project, they only need to be good enough for the current situation. I tend to use inclusive tools such as whiteboards and paper to do the initial versions of these models, but if my fellow team members have more sophisticated modeling skills and if the tools are available then I'll capture this information in software-based modeling tools such as Rational Software Architect (RSA) and thereby take advantage of code generation and reverse-engineering capabilities.

How Much Initial Architecture Modeling?

Many traditional developers will struggle with an agile approach to initial architecture envisioning because for years they've been told they need to define comprehensive models early in a project. But, if you were to step back and think about it for a bit, this really doesn't make much sense in practice. To see this, let's consider some common situations that you might find yourself in and ask how much initial architectural modeling you would need to do. These scenarios are summarized in Table 1.




Agile Architecture Strategy


You are working with known technologies that you are experienced with


You need to do very little initial modeling because you know what you're doing. Create a whiteboard sketch or two to ensure that everyone is working to the same vision and then continue on


You have little or no experience with the technologies


You need to do very little initial modeling because you don't know what you're talking about. Do a little bit of modeling to identify a plausible strategy, then prove (or disprove) your strategy by developing an end-to-end working skeleton of your system. The rest of your software will be designed on a JIT basis throughout your project. In this situation detailed models would likely be ignored by the developers because they're quickly recognize that you didn't know what you were modeling. They will also give you a false sense of confidence, increasing project risk, and you'll be much more likely to commit to your flawed architectural vision due to the effort you put into documenting it, also increasing project risk.


Some architectural issues are known but there are a few unknowns.


This is the common, middle-ground situation that most teams find themselves in. It makes sense to do a little more modeling initially (perhaps even several days) so as to identify potential risks and likely strategies to mitigate them. You'll still want to prove your architecture with working code and identify details on a JIT basis. Modeling makes sense in this situation because it enables you to define a shared technical vision within the team and to potentially think through major issues.


Table 1. Common architectural scenarios

You will gain significant value from initial architectural modeling when your team is dispersed amongst several sites, or if it's large, or if you have several subteams because it will help you to organize your efforts. It helps you to grow a common vision between the subteams but more importantly you can identify separate components/subsystems, and the initial interfaces to those components, which can then be assigned to the subteams. These interfaces will evolve over time, so you'll need to collaborate with one another throughout the project, but once again some initial architecture modeling will provide significant benefit.

Why Architectural Envisioning?

Some people will tell you that you don't need to do any initial architecture modeling at all. However, my experience is that architecture envisioning offers several benefits:

  1. Improved productivity. You can think through some of the critical technical issues facing your project and potentially avoid going down fruitless technical paths.
  2. Reduced technical risk. Your team gains the advantage of having a guiding vision without the disadvantage of having to overbuild your system - just because you've modeled it doesn't mean you have to build it.
  3. Reduced development time. Initial agile architecture envisioning enables you to make better cost and time estimates for your project, two pieces of information which management will want.
  4. Improved communication. Having a high-level architecture model helps you to communicate what you think you're going to build and how you think that you'll build it, two more critical pieces of information desired by management.
  5. Scalable agile software development. Your initial architecture model will be a key work product in any "agile at scale" efforts because it provides the technical direction required by sub-teams to define and guide their efforts within the overall project.

According to some of the more extreme rhetoric out there you shouldn't do any initial architectural modeling because of the fear of overbuilding. In my experience this fear is not only unjustified it actually decreases your team's overall effectiveness. First, just because you're choosing to think through some critical issues early in the project doesn't mean that you need to overbuild your system at the beginning - albeit, it does require you to have a bit of discipline on your team, perhaps belying people's true fear that they aren't sufficiently disciplined. Second, very few project teams find themselves in a truly unconstrained, greenfield situation. Most organizations already have an existing architecture in place, for example they may have a J2EE infrastructure based on Websphere and DB2. The implication is that your team may be in a position to add very little new technology to the mix, perhaps a business rules engine, but it's unlikely that you'll be able to select another application server or database platform. This is true regardless of how long it takes you to evolve your solution into these "architectural decisions" which were made years ago or how much mocking you do. Third, the make up of your team often determines your architecture. For example, if you only have Perl programmers, Java programmers, and Ruby programmers on staff, chances are exceptionally good that your architecture will be based on Perl, Java, or Ruby technologies regardless of whether these platforms are truly the best choice for you.

The implication is that in many cases architectural decisions have been made long before your project even started. Disciplined agile developers recognize this and choose to invest in a bit of up front modeling to leverage these known things and thereby reduce overall technical risk on their projects.

[i] Ambler, S.W. (2003). Agile Model Driven Development: The Key to Scaling Agile Software Development.

[ii] Ambler, S.W. (2007). Dr. Dobb's Journal 2007 Agile Adoption Survey.

[iii] Ambler, S.W. (2004). Agile/Evolutionary Data Modeling: From Domain Modeling to Physical Modeling.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.