focuspostmodern software design Architecture Decisions: Demystifying Architecture Jeff Tyree and Art Akerman, Capital One Financial t’s hard to count the “mystical” software architectures we’ve reviewed You can make over the years. Their creators seem to want us to take many things on your architecture faith. They require us to assume that the solution is somehow tied to more transparent business drivers, that their architectural choices have rationales and and clarify its I are implementable, and that they adequately considered competing alterna- rationale for tives. Yet at times, the architecture seems to have no grounding in business all stakeholders needs, and it’s difficult to see if the architects understand their decisions’ by explicitly implications for the environment in which the guidance on how to proceed with a design. Cus- documenting architecture is to be deployed. We believe that tomers want a clear understanding of the envi- major architecture a key to demystifying architecture products— ronmental changes that must occur and assur- decisions. to dispel or reduce the “magic”—lies in the ar- ance that the architecture meets their business chitecture decisions concept. needs. Other architects want a clear, salient un- derstanding of the architecture’s key aspects, in- Why architecture decisions? cluding the rationale and options the original ar- Decisions. We make them every day. Some are chitect considered. big, some small. So what’s the big deal? In most Traditional architectural approaches such architecture development processes, decisions as RM-ODP (Reference Model for Open Dis- aren’t documented explicitly but are implicit in tributed Processing), 4+1, or RUP (Rational the models the architect builds. Architects make Unified Process) don’t satisfy these wants in a structuring decisions, such as choosing patterns, clear and simple manner.1–3 These approaches in the component (logical) model, and deploy- break down in several areas, such as ment decisions, such as choosing runtime pat- terns, in the physical model. However, stake- ■ Conveying change. In an evolutionary envi- holders such as developers, customers, and ronment, it is challenging to document ar- even other architects don’t have the energy to chitecture changes through conventional pore through architectural views to understand views in a way developers or designers can the architecture. Developers want clear, decisive understand. Developers don’t want to wade 0740-7459/05/$20.00 © 2005 IEEE March/April 2005 IEEE SOFTWARE 19 through a lengthy component model just to essary for an architect to make and explicitly find a few key items that have changed. In document all of them? We agree with Ruth A simple addition, in an environment where object Malan and Dana Bredemeyer,4 who argue that document orientation isn’t the norm, many developers an architect should make as few decisions as aren’t familiar with component models and possible, deferring the rest until later in the describing key interaction diagrams. They’re just looking lifecycle. This lets the architect maintain a bal- architecture for changes to the architecture’s key aspects ance between guiding and constraining the that will influence their design. technical organization. An architect absolutely decisions can ■ Conveying implications. Traditional ap- should make the decisions that identify the go a long way proaches don’t clearly state the architecture’s system’s key structural elements, their exter- in demystifying implications. What are the organizational nally visible properties, and their relation- impacts? What are the training needs? ships.5 To test a decision’s architectural signif- past and future ■ Conveying rationale and options. Tradi- icance, an architect should ask the following system tional approaches tend to rely on models question: does this decision affect one or more to convey the majority of the architec- system qualities (performance, availability, architectures. ture’s information. They don’t focus on modifiability, security, and so on)? If so, an ar- the rationale and options the architect chitect should make this decision and docu- considered. Without these two key ele- ment it completely. ments, stakeholders begin to ask the same Properly documenting these architecture de- questions again and again—questions that cisions is critical because architects make them have long been answered. in complex environments and they involve ■ Ease of traceability. Traceability is chal- trade-offs. How many times have we looked at lenging in many respects, regardless of the an architecture and been surprised (or even ter- development lifecycle phase. The chal- rified) by the decisions it was based upon? Our lenge of mapping the objectives (which we first reaction is to ask several rhetorical ques- define as business needs, risks, system is- tions: “What were these people thinking? Had sues, change cases, and nonfunctional re- they never heard of sound principles of good quirements) to specific architectural ele- design? Did they think that the system wouldn’t ments is unmanageable. We need a simpler live longer than a month?” Well, okay, maybe way to ensure that the architecture meets a few were inexperienced, short-term thinkers. its objectives. But most had good intentions and did what ■ Providing agile documentation. Tradi- seemed right in the moment. The decisions tional approaches tend to rely on architec- made sense under the circumstances, which ture expression through a set of views. cost and schedule constrained. However, look- We’ve found it necessary to provide alter- ing back, after the dust has settled and the orig- native documentation forms that balance inal system designers are long gone, we have architectural and agile objectives. no context around these decisions; we have no history. All we can do is shake our heads in dis- To address these breakdowns, we believe belief. In the end, as Gustave Flaubert report- that architecture decisions are the missing edly wrote in 1871, “Our ignorance of history link. If we elevate architecture decisions to causes us to slander our own times.” first-class status and explicitly document and A simple document describing key architec- socialize them, they become an effective tool ture decisions can go a long way in demystify- to help stakeholders understand the architec- ing past and future system architectures. ture. If an architect doesn’t have time for any- IBM’s e-Business Reference Architecture thing else, these decisions can provide a con- Framework, where architecture decisions are a crete direction for implementation and serve key deliverable, has helped us learn how to as an effective tool for communication to cus- document these decisions.6 Table 1, derived tomers and management. from the REMAP (Representation and Mainte- nance of Process Knowledge) and DRL (Deci- What exactly are architecture sion Representation Language) metamodels, decisions? lists the essential information for each deci- A complex architecture probably reflects sion.7 We’ve added two additional fields, re- thousands of decisions, big and small. Is it nec- lated principles and notes. 20 IEEE SOFTWARE www.computer.org/software Table 1 Architecture decision description template Issue Describe the architectural design issue you’re addressing, leaving no questions about why you’re addressing this issue now. Following a minimalist approach, address and document only the issues that need addressing at various points in the life cycle. Decision Clearly state the architecture’s direction—that is, the position you’ve selected. Status The decision’s status, such as pending, decided, or approved. Group You can use a simple grouping—such as integration, presentation, data, and so on—to help organize the set of decisions. You could also use a more sophisticated architecture ontology, such as John Kyaruzi and Jan van Katwijk’s, which includes more abstract categories such as event, calendar, and location.8 For example, using this ontology, you’d group decisions that deal with occurrences where the system requires information under event. Assumptions Clearly describe the underlying assumptions in the environment in which you’re making the decision—cost, schedule, technology, and so on. Note that environmental constraints (such as accepted technology standards, enterprise architecture, commonly em- ployed patterns, and so on) might limit the alternatives you consider. Constraints Capture any additional constraints to the environment that the chosen alternative (the decision) might pose. Positions List the positions (viable options or alternatives) you considered. These often require long explanations, sometimes even models and diagrams. This isn’t an exhaustive list. However, you don’t want to hear the question “Did you think about … ?” during a final review; this leads to loss of credibility and questioning of other architectural decisions. This section also helps ensure that you heard others’ opinions; explicitly stating other opinions helps enroll their advocates in your decision. Argument Outline why you selected a position, including items such as implementation cost, total ownership cost, time to market, and required development resources’ availability. This is probably as important as the decision itself. Implications A decision comes with many implications, as the REMAP metamodel denotes. For example, a decision might introduce a need to make other decisions, create new requirements, or modify existing requirements; pose additional constraints to