Architectural Decisions as Reusable Design Assets

This article first appeared in IEEE Software Magazine and is brought to you by InfoQ & IEEE Computer Society.

Software architects make many decisions when creating designs. The importance of getting key architectural decisions right is well documented.^1-3 However, it can be difficult to generalize what the key decisions are, let alone when and how to make them. In the past, architectural decisions have been characterized as the subset of design decisions that are hard to make⁴ and costly to change.⁵ To help clarify these issues, the following definition adds several qualification heuristics⁶:

Architectural decisions capture key design issues and the rationale behind chosen solutions. They are conscious design decisions concerning a software-intensive system as a whole or one or more of its core components and connectors in any given view. The outcome of architectural decisions influences the system’s nonfunctional characteristics including its software quality attributes.

According to this definition, choosing a programming language, architectural pattern, application container technology, or middleware asset are all architectural decisions. For instance, integration patterns such as Broker describe the many forces confronting distributed systems, including location independence and networking issues.⁷ These forces qualify as decision drivers, so adding Broker to an architecture is an architectural decision that should be justified. State-of-the-art software engineering methods, such as the IBM Unified Method Framework, call for architectural decision logs to document and justify key decisions in a single place.⁸

The logs help preserve design integrity in allocating functionality to system components. They support an evolving system by ensuring that the architecture is extensible. They also provide a reference for new people joining a project to avoid reconsideration of issues already decided. The logs capture architectural decisions after the fact. Creating such logs is a documentation activity with many long-term but few short-term benefits.⁹ If we relax the assumption of documentation rigor on a particular project and assume instead that multiple projects in an application genre follow the same architectural style - that is, share the same principles and patterns - we can consider the option of upgrading architectural decisions from documentation artifacts to design guides.

These guides can help architects working in a particular application genre and architectural style understand decision-making needs and solution options on the basis of peer knowledge applied successfully in similar situations. In this way, recurring architectural decisions become reusable assets, just as methods and patterns are. This gives rise to novel usage scenarios. For in- stance, recurring issues can serve as review checklists, help prioritize design and development work items, and improve communication between enterprise and project architects.

SOA Decision-Modeling Framework

The first step in giving recurring architectural decisions a guiding role during design is to effectively capture and generalize related project experience. This is a knowledge engineering activity. Service-Oriented Architecture (SOA) Decision Modeling (SOAD) is a knowledge management framework that sup- ports this activity.¹⁰ SOAD provides a technique to systematically identify the decisions that recur when applying the SOA style in a particular genre, such as enterprise applications. SOAD enhances existing metamodels and templates,^8,11 specifically by distinguishing decisions required from decisions made. It establishes a multi level knowledge organization that separates platform-independent from platform-specific decisions. On the conceptual level, the design alternatives reference architectural patterns, such as those defined by Martin Fowler¹² and others.^7,13,14

The SOAD framework lets knowledge engineers and software architects manage decision dependencies, so they can check model consistency and prune irrelevant decisions. A managed-issue list guides the decision-making process. Supported by the framework, architects can update design artifacts according to decisions made by injecting decision outcomes into model transformations.⁶

In support of reuse, the SOAD metamodel defines two model types:

• guidance models to identify decisions required and
• decision models to log decisions made.

Figure 1 shows the relations and internal structures of these model types.⁶

FIGURE 1. The Service-Oriented Architecture (SOA) Decision Modeling (SOAD) framework. The SOAD metamodel is instantiated into a guidance model that identifies the decisions required for a particular architectural style, such as SOA. Architects can tailor the guidance model to create an initial decision model for a project.

A guidance model is a reusable asset containing knowledge about architectural decisions required when applying an architectural style in a particular application genre. The model is based on knowledge captured from already-completed projects that employed the architectural style in that genre. As Figure 1 shows, an issue informs the architect that a particular design problem exists and requires an architectural decision. Issues present decision driver types, such as quality attributes, and reference alternative potential solutions along with their advantages (pros), disadvantages (cons), and known uses in previous applications. A knowledge engineer documents the issues and alternatives, writing in the future tense and a tone that a technical mentor would choose in a personal conversation.

The guidance model feeds project- specific architectural decision models in a tailoring step that might involve deleting irrelevant issues, enhancing relevant ones, or adding new issues. The decision model is an architecture documentation artifact that contains knowledge not only about architectural decisions required but also about architectural decisions made. An outcome is a record (log) of a decision actually made on a project, along with its justification. In SOAD, outcomes represent a form of design workshop minutes that software architects capture in the present or past tense. A decision model can reuse one or more guidance models. It can feed information about decisions made back to the guidance model after project closure via asset harvesting activities that might include informal or formal lessons learned reviews. In SOA design, for instance, an insurance company’s business process model might state that back-end systems must implement and integrate three business activities and corresponding service operations: customer inquiry, claim check, and risk assessment.

The architect must select an integration style for this purpose, such as one of the four alternative patterns that Gregor Hohpe and Bobby Woolf identified for this issue: File Transfer, Shared Database, RPC, or Messaging.¹³ The architect must also select an integration technology, such as HTTP and Java Message Service (JMS) that lets the business activities interact with other systems. A problem statement ("Which technology will be used to let the business activities and service operations in the business process communicate with other components, such as legacy systems?") and decision drivers ("interoperability, reliability, and tool support") are the same for all three service operations.

Project-specific decision outcomes, such as the chosen alternative and its justification, depend on each operation’s individual requirements. For example, "For customer inquiry, we selected RPC and HTTP because Java and C# components must be integrated in a simple and interoperable manner, and we value the available Web services tool support." Or, "For risk assessment, we selected Messaging and JMS because some of the involved back-end systems are known to have poor avail- ability and we cannot afford to lose messages."

From General Issues to a SOA Guidance Model

I will use the insurance company example to generalize and extend the two decisions required - that is, the integration style and integration technology issues. The first step is to add general is- sues that occur in layered client-server architectures to a generic component-and-connector diagram. In Figure 2, the components and connectors are generalizations of service consumers (clients) and providers (servers) in a layered system.

FIGURE 2. General issues in generic component-and-connector architectures. Each component and connector yields concrete issues derived from general issues. Transitions to next realization levels include, for example, conceptual to specified to implementation component models.

For instance, layer n might be instantiated into the presentation, business-logic, and persistence layers of a service-oriented enterprise application.¹² In such an instantiation, the three business activities and service operations from the insurance example (customer inquiry, claim check, and risk assessment) are components in the architecture’s business-logic layer. Every question fragment (for example, in Figure 2, "Interface signature?") then suggests a general issue that has to be investigated when refining the design into a concrete architecture. The second step is to combine the general issues with SOA patterns. Several authors have described such SOA patterns - for example, Uwe Zdun and his colleagues.¹⁴ The SOAD framework uses the following SOA definition:⁶

From an architecture design perspective, SOA introduces a Service Consumer (requestor), a Service Provider, and a Service Contract. These patterns promote the architectural principles of modularity and platform transparency. A composite architectural pattern, ESB (Enterprise Service Bus), governs the service consumer-provider interactions and physical distribution in support of principles such as protocol transparency and format transparency. The Service Composition pattern organizes the processing logic, adhering to the principles of logical layering and flow independence. The Service Registry pattern defines how service providers are looked up; related principles are location transparency and service virtualization.

Instantiating the generic client-server components into a functional architecture overview, Figure 3 illustrates how these patterns and their building blocks interact in a SOA.⁶

According to the figure, the essence of the SOA style is the decoupling of service consumer and service provider via the service contract, ESB messaging, and the service registry. The ESB pattern comprises three other pat- terns: Mediator, Router, and Adapter. To separate platform-independent from platform-specific design, this patterns- based characterization of SOA omits Web services or other technologies. Combining the general issues from Figure 2 with the SOA patterns from Figure 3 leads to concrete recurring is- sues. Identifying issues and alternatives this way allows knowledge engineers to harvest decision drivers, pros, cons, and recommendations from project experience with the patterns.

FIGURE 3. SOA patterns and their collaborations and functional decomposition. Service consumers and providers communicate via the ESB pattern. A service registry lists the service contracts and providers that are available to service consumers.

Executive Decisions

Assuming SOA is the preferred architectural style, which is an executive decision in its own right, the selection of a particular SOA reference architecture is an executive-level decision. It requires agreement on terminology, such as layer and component names, and identification of relevant pattern languages. Architectural principles - for example, to prefer open source assets or certain software vendors and server infrastructures - might also take the form of executive decisions. The corresponding general issue in Figure 2 is "Overall layer organization?"

Conceptual, Platform-Independent Design Issues

A service designer must decide on the granularity of service contracts in terms of operation signatures for request and response message parameters. These signatures specify the service’s invocation syntax as well as the message payload structures. The issue deals with service contract design. The service contract, a SOA pattern according to Figure 3, is the SOA instantiation of an interface; hence, the general issue called "Interface signature?" applies in this design context, according to Figure 2. The detailed ESB design and configuration trigger another set of issues. Architects must select message exchange patterns, such as one way and request- reply (asynchronous versus synchronous communication). They must also detail usage of the Router, Mediator, and Adapter patterns, describing how to maneuver messages from service consumers to service providers (Router), how to transform message content while it’s transported on the ESB (Mediator), and how to integrate non-SOA systems and components (Adapter).¹³

Architects following the SOA style must also refine the service composition design (if they select this SOA pattern). The choice of a central Process Manager¹³, such as a workflow engine (as opposed to distributed state management in individual applications or components), is an important related architectural decision regarding the internal structure of the business-logic layer. Design time versus runtime registry lookup is an example design issue regarding service registries. "Component life-cycle management?" is the related general issue (see Figure 2).

Platform-Related Design Issues

None of the conceptual design issues deals with technology standards or their implementations. However, archi­tects that select one or more SOA pat­terns must also resolve such platform-related issues - for example, selecting and profiling implementation technolo­gies such as WS* Web services for the integration technology. Once the tech­nologies have been chosen, the architect must select and configure implementa­tion platforms. Many SOA patterns are implemented in commercial and open source middleware. The architect must decide whether to procure such middle­ware and, if so, how to install and con­figure it.

Reusable Design Asset: SOA Guidance Model

All the SOA design issues I’ve described qualify as architectural decisions ac­cording to the definition presented in the introduction. For instance, a ser­vice’s operation signature influences quality attributes such as performance and interoperability. Moreover, these issues recur. Whenever a project ap­plies SOA patterns, it must resolve the corresponding issues one or more times. Knowledge reuse is therefore desirable.

I’ve compiled 500 such recurring is­sues in a SOA guidance model.^6,10

SOAD Case Study Reports

Practicing architects have applied SOAD and the SOA guidance model successfully to more than 10 projects. These projects dealt with a pension plan management application for a Eu­ropean country’s social security agency, customer- and order-management so­lutions for a telecommunications com­pany, and business-to-business applica­tions for a multichannel retailer. The case studies confirmed that many issues recur. Participating architects assessed the knowledge in the SOA guidance model to be both relevant and action­able. They reported improved speed and quality in design activities and gen­eral appreciation for the SOAD vision and approach.^6,9

Feedback for the SOAD Framework

During the case study projects, I inter­acted with several hundred architects to obtain their feedback regarding the value and usability of SOAD. Only one of them disagreed openly with the fun­damental SOAD hypothesis that ar­chitectural decisions recur when the same architectural style is employed on multiple projects in an application genre, and this objection turned out to be a misunderstanding. SOAD doesn’t claim that a decision always has the same outcome; it claims only that the issue, expressing the need for a deci­sion, recurs.

Case study participants saw the SOAD metamodel’s attributes as intui­tively understandable, conveying useful and sufficient information to help make key decisions. They suggested a few ad­ditional attributes. They also suggested different ways of structuring the guid­ance models - including the organiza­tional dimensions defined by enterprise architecture frameworks.

Participants saw decision-depen­dency management as an important advantage of decision modeling be­cause managing dependencies in text-based decision logs is difficult. They also pointed out that mature design methods exist already and that any additional method must align with these. They saw SOAD as a supporting asset - a decision-making technique em­bedded in a general-purpose method - rather than a stand-alone method.

Feedback for the SOA Guidance Model

Case study participants appreciated the guidance model’s content and level of detail. They saw it as appropriate to terms of being not obvious, relevant to SOA industry projects, and clearly documented.

There was some confusion regarding proactive versus retrospective decision modeling. One user simply copied the issue descriptions and recommendation attributes from the guidance model to outcome justifications in the decision log. This provoked negative comments from a senior architect in a team-inter­nal technical quality assurance review. In conclusion, the expectations regard­ing the use of SOAD must be managed. SOAD doesn’t intend to make architec­tural thinking obsolete.

Usage Scenarios and Discussion

SOAD is a decision-centric approach to guiding design work. One of its bene­fits is that the target audience, software architects, already knows the core con­cept of architectural decisions from a different usage scenario - namely, ar­chitecture documentation. This sim­plifies SOAD applications to other scenarios:

• IT users could maintain control over their application landscape by asking suppliers to deliver a stan­dardized decision log along with their software solution or prod­uct. Users could structure the de­cision logs according to the SOAD metamodel and populate them from a shared guidance model.
• Companies that develop multiple software-intensive products or product lines could ask their enter­prise architects to create a company-wide guidance model. Method and tool groups could support guid­ance modeling activities by adopt­ing a company-specific SOAD metamodel. This approach would shorten time to market and help preserve architectural consistency across products.
• Software vendors with complex portfolios could reduce train­ing, customization, and sup­port efforts by sharing technical knowledge in guidance models that are annotated with best-practice recommendations.
• In professional services, communities of practice that value explicit knowledge management and reusable assets could create guidance models to support a shift from labor-based to asset-based delivery models (strategic reuse).
• Trainers could use guidance models as a systematic way of teaching pat- terns and technology best practices.
• Analysts and auditors who want to evaluate middleware and enterprise applications in a repeatable, efficient way could base standardized, domain-specific questionnaires on recurring design issues. They could model these issues according to the SOAD metamodel.

SOAD assumes that many issues recur. If they don’t, a guidance-model asset won’t provide sufficient value to justify its creation. If multiple projects employ the same architectural style, the assumption that issues recur will likely hold. However, using SOAD to describe the issues and alternatives involves a commitment to knowledge engineering. A guidance model must meet higher editorial standards than project-specific decision logs, so a decision to create such a model must support a knowledge management strategy. It needs a funding model as well as a review, approval, and maintenance process. My results over the course of three years’ experience with SOAD showed that, on average, knowledge engineers can fully model one issue in one person day.

Architects can already benefit from incompletely modeled knowledge, such as issue checklists articulating problem statements in question form. Moreover, tools can partially automate asset harvesting - for instance, mining tools extracting architectural knowledge from project artifacts. From a tool-design perspective, the amount of information displayed and the context-specific filtering and ordering capabilities are key success factors. Architects typically spend much of their time communicating with external and internal stakeholders, so they might not be willing to read a guidance model end to end (although some of my colleagues have done just that). Tools can trim the guidance model down to the issues and alternatives that are relevant in a given design context, first during the tailoring step and then throughout the project. The SOAD metamodel supports such tool development, for example, by giving issues a scope attribute and by calling out the project phase in which an issue typically is resolved.

Conclusion

SOAD was originally created to support enterprise application and SOA design, but the use of guidance models as reusable assets also applies to other application genres and architectural styles. It supports application scenarios such as education, knowledge exchange, design method, and governance. Next steps for its development include extending it to other business and technology domains as well as target audiences, such as business people in addition to software architects. Other plans address guidance modeling challenges such as knowledge visualization and maintenance.¹⁵

By promoting the reuse of architectural knowledge in the form of guidance models that compile recurring is- sues and options, SOAD lets architects share best practices in a problem-solution context. We may learn best from mistakes, but who said all the mistakes must be our own?

About the Author

Olaf Zimmermann is a research staff member at IBM Research-Zurich. His research interests focus on application and integration architecture, SOA design, architectural decisions, and frameworks for service and knowledge management. Zimmerman has a PhD in computer science from the University of Stuttgart. He’s an Open Group Distinguished IT Architect, IBM Executive IT Architect, and author of Perspectives on Web Services (Springer, 2003). Contact him at olz@zurich.ibm.com.

References

1. L. Bass, P. Clements, and R. Kazman, Software Architecture in Practice, 2nd ed., Addison-Wesley, 2003.
2. N. Rozanski and E. Woods, Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives, Addison- Wesley, 2005.
3. P. Eeles and P. Cripps, The Process of Soft- ware Architecting, Addison-Wesley, 2010.
4. M. Fowler, "Who Needs an Architect?" IEEE Software, vol. 20, no. 5, 2003, pp. 2-4.
5. G. Booch, internal conference presentation to IBM Academy of Technology, 27 Apr., 2009.
6. O. Zimmermann, "An Architectural Decision Modeling Framework for Service-Oriented Architecture Design," PhD thesis, Univ. of Stuttgart, 2009.
7. F. Buschmann, K. Henney, and D. Schmidt, Pattern-Oriented Software Architecture, Vol. 4 - A Pattern Language for Distributed Computing, Wiley, 2007.
8. IBM Unifi ed Method Framework, work product description (ARC 0513), IBM, 2009.
9. M. Ali Babar et al., eds., Software Architecture Knowledge Management: Theory and Practice, Springer, 2009.
10. O. Zimmermann et al., "Managing Architectural Decision Models with Dependency Relations, Integrity Constraints, and Production Rules," J. Systems and Software and Services, vol. 82, no. 8, 2009, pp. 1246-1267.
11. J. Tyree and A. Ackerman, "Architecture Decisions: Demystifying Architecture," IEEE Software, vol. 22, no. 2, 2005, pp. 19-27.
12. M. Fowler, Patterns of Enterprise Application Architecture, Addison-Wesley, 2003.
13. G. Hohpe and B. Woolf, Enterprise Integration Patterns, Addison-Wesley, 2004.
14. U. Zdun, C. Hentrich, and S. Dustdar, "Modeling Process-Driven and Service-Oriented Architectures Using Patterns and Pattern Primitives," ACM Trans. Web, vol. 1, no. 3, 2007, article no. 3; doi.10.1145/1281480.1281484.
15. M. Nowak, C. Pautasso, and O. Zimmermann, "Architectural Decision Modeling with Reuse: Challenges and Opportunities," Proc. 2010 ICSE Workshop Sharing and Reusing Architectural Knowledge (SHARK 10), ACM Press, 2010, pp. 13-20.

This article first appeared in IEEE Software Magazine issue Jan/Feb 2011, pp. 64-69. IEEE Software Magazine offers pioneering ideas, expert analyses, and thoughtful insights for software professionals who need to keep up with rapid technology change.