Architecture Description Really Matters

By: Yan Zhao, Ph.D

I was hired many years ago as a corporate level principal architect. The first assignment I got was to describe the architecture of an existing software system product inherited from a company acquisition. The original people who created the system had left the company. There were no architecture or design documents; no one had insight about it to be able to describe what it really was. Folks didn’t know how to market it to external customers, so the product faced the “death penalty.” To the engineering teams who understood something of the system however, the product was current, state-of-the-art, and very competitive with lots of great ideas built-in. By collecting information from multiple channels, I provided the architecture description for this system, and did it justice. Also, I provided an architecture for its future evolution. Both marketing folks and engineering teams were happy with the results. By sharing my experience, I will show what is involved with creating an architecture description, and how we architects can perform our roles effectively. In the context of overall architecture design, the goal of creating an architecture description is to transform the collected and organized architectural information and intents into viable models. The creation and adoption of effective architecture approaches, methodologies, patterns, reference models, and so on, can certainly benefit architecture description. The architecture description is the end product of an architecture development process, and it is the ultimately visible representation of architecture. Let’s look at more details in the following sub-sections.

Establish Vision and Insight

In order to provide construction guidance, as well as to support marketing in fulfilling potential customer needs, architecture has to have vision and insight, which is crucial for product success. For my architecture description assignment mentioned above, the first thing I did was to understand the purpose of the system, its goal, and possible usage scenarios. I did feel pressure at the beginning as a new person in the company; I was not sure if my review and description document could make both marketing and engineering happy. I decided to take a forward-looking approach based on what I had learned of the system’s purpose and goals. Then, I performed detailed product studies with help from the engineering team. I tried to line-up their current product with clear future vision and insight. By doing that, I was able to bring both marketing and engineering folks together to a common page in moving forward. Architecture is a creative art, even if it is based on an existing legacy system. It is not only for engineering or construction guidance, but it also has to provide insight, intent, and vision, so that it can guide the system in moving forward through continual evolution.

Identifying Architecture Scope and Audience

To make the architecture description content effective and well accepted, we need to identify the scope of our architecture coverage and the intended audience, so that we can cover the right material to meet peoples’ interests and backgrounds. For this architecture description assignment, my audiences clearly included marketing and engineering, as well as management. The scope of my architecture description had to incorporate the interests of all the involved parties, and had to be able to answer their questions from different perspectives. In order to achieve that, I planned my architecture content to cover different levels and aspects in different sections, with the common high-level content at the beginning. To support my content, I decided to create a couple of diagrams to describe the concept of the software system operations and its associated application scenarios for both “as-is” and “to-be” products. This approach did help in bringing people from different roles together to have a common understanding about the software product. A successful architecture description has to consider the background of the audience in order to determine the scope the architecture should cover. You have to be able to describe your concepts to different audiences such as customers, sales and marketing folks, management, and engineering teams, so that you can get buy-ins, support and funding, and get it implemented to achieve real value.

Information Gathering

Information gathering is a critical step for the creation of architecture. The information quality and coverage will affect the accuracy of architecture description. For the assignment mentioned above, after the architecture description content strategy was decided upon based on scope and audience, the next step for me was to perform information collection, analysis, synthesizing, and modeling. This was an iterative process. The token steps included:

• Identify interviewees

• Communicate architectural intent, concepts, and activities to the interviewees and relevant people

• Conduct interviews and collect information from multiple channels (e.g. conversation, segments of design documents, emails, meeting minutes, etc.)

•  Synthesize and conceptualize the information, and organize them into models and documents

• Conduct reviews with relevant people, and further improve and extend the architectural model descriptions

Effective information collection and synthesizing are very important in establishing a foundation and baseline for architecture description. The architecture is more easily accepted by stakeholders if it reflects their views.

Models and Views of Architecture Creation

In the information gathering steps described in the last section, we mentioned architecture modeling in the last two steps that were performed iteratively with information gathering and synthesizing processes. For architecture modeling, we need to select an architecture style, identify architecture principles (or constraints), and determine views for the presentation of architecture models. The models and views are the core of an architecture description. Based on my experience in CORBA (Common Object Request Broker Architecture) and object-oriented paradigms, I selected component-based and service-oriented architecture styles, which suited the existing Java-based development environment very well. I started with some conceptual diagrams of the software system operations, which helped in establishing common understanding. An example is illustrated in Figure 1.

Figure 1—The concept of operation diagram for a software system  
The component-based architecture for the software system was based on the diagrams of the concept of operations. The operational components were mapped and decomposed to implementable software components. The components and their inter-operation relationships are illustrated in Figure 2. 

 
Figure 2—A component-relationship diagram for component-based software architecture
Software architecture is the structure, or structures, of the system that comprise software components, the externally visible properties of those components, and the relationships between them
[Bass, et al. 1998]. The term structure means a model or view of a system. Components are the architectural objects in each of these views. For current practice, some standard architecture description languages can be considered as well, though they are not in the scope of this article. These are terms such as, Architecture Description Language (ADL), Architecture Description Markup Language (ADML), etc. Information on these is widely available in public domain (e.g. on the web).

Competitive Analysis and Technology Options

In response to marketing requests for a software product, competitive analysis of the market was necessary. To support my architecture vision and views, I summarized major competitive products in the landscape with an analysis of their pros and cons both in features and in technical implementations. Based on that competitive analysis, our product position was justified. If competitive analysis is to make marketing folks comfortable, the technology options for the described architecture are to convince and provide guidance for the engineering teams in actual product implementation. In the architecture description document, what I included were options for platforms and development tools, technology standards, available COTS (Commercial/Off-The-Shelf) products, and so on. I also mapped the logical architecture to the physical architecture in terms of implementable software components by using selected technologies and COTS products, which the engineering teams liked to see. A good architecture description should provide a viable position for marketing, as well as clear guidance for engineers to implement the design based on the current state-of-the-art technology.

Roadmap for Engineering

We all know that software products go through versions. It is impossible to implement all the features at once. Therefore, product development is also an iterative process with a phased product life cycle. With considerations in changing requirements from market, technology advancement, architecture dependencies, available budget, and other possible factors, a roadmap for engineering will provide guidance on which feature or software component will be implemented first, and which will be implemented next, or later on. I provided an engineering roadmap in my description of architecture, which was crafted based upon current product and direction. It prioritized the extension components based on marketing requirements, technical viability, component’s mutual dependencies, cost, etc. The roadmap was also a tool that brought different parties into the same page and set compatible expectations for them in playing their roles upon moving forward. A good architect should be able to create a roadmap for engineering based on the architecture created. The roadmap should reflect his/her insight and vision, as well as knowledge in component dependencies, technology availabilities, marketing priorities, and so on. For construction, regardless of whether it is a building or a computer software system, the architecture description is critical for success. It expresses a creative art in terms of insight, vision, usage scenarios, structural models, processes, technology options for implementation, and so on. Software architecture is a live conceptual art; it has its own life cycle in inception, creation, updates and maintenance. Its insight, intent, vision, and models can guide the software implementation moving forward through continuous evolutions. The effectiveness of architecture description has to consider multiple aspects:

• The considerations of purpose, scope, and audience are helpful for its guiding position, as well as for its acceptance and buy-in.

• Effective information collection and synthesizing are important in establishing a baseline for architecture description. The architecture will be more easily accepted by stakeholders if it reflects their views.

• We have to create different models and views for the same concepts to suit people in different roles, responsibilities, and background.

• Market analysis, technology options, and implementation roadmaps are helpful in bringing architecture to reality in an iterative and phased manner.

 

Critical Thinking Questions

The following are some critical thinking questions that architects should think about before getting into architecture description:

• What is the scope of the architecture?

•  Who are the intended audiences for the architecture description?

• What architecture style should be used for architecture description?

• What approaches and methodologies should be adopted?

• Are there any helpful tools?

 

Sources

[Bass, et al. 1998] Bass L, Clements P, and Kazman R. 1998.Software Architecture in Practice. Addison-Wesley Publishing Co., Reading, MA .

About the Author

 Dr.Yan Zhao is the founder at ArchiTech Group LLC. An enterprise level chief architect, strategist, innovator, and executive with a Ph.D in Computer Science. Has over 20 years work experience across academia, corporate research, software industry, and consulting service. Was a university faculty member, a guest and an adjunct professors. Has 6 patents granted, 4 patents pending, and a number of invention disclosures, technical publications.