Chapter 7. Architectural Perspective

“To design something really well, you have to get it. You have to really grok what it’s all about. It takes a passionate commitment to really thoroughly understand something, chew it up, not just quickly swallow it.”

Steve Jobs

“A little perspective, like a little humor, goes a long way.”

Allen Klein

“A lot of people in our industry haven’t had very diverse experiences. So they don’t have enough dots to connect, and they end up with very linear solutions without a broad perspective on the problem. The broader one’s understanding of the human experience, the better design we will have.”

Steve Jobs

“Perspective gives us the ability to accurately contrast the large with the small, and the important with the less important. Without it we are lost in a world where all ideas, news, and information look the same. We cannot differentiate, we cannot prioritize, and we cannot make good choices.”

John Sununu

“So when these people sell out, even though they get fabulously rich, they’re gypping themselves out of one of the potentially most rewarding experiences of their unfolding lives. Without it, they may never know their values or how to keep their newfound wealth in perspective.”

Steve Jobs

Architects are usually the first technology people to get involved with the business on a new idea. Depending on the timing and the level of engagement of the business, this can be as early as ideation or as late as when the product is already wireframed and an estimate is needed. If all goes well, the architect will be included earlier rather than later.

The spanning type of role for architects gives them a unique view into the world of building products. Architects therefore need to understand not only what the business wants to accomplish, but also what is logical, feasible, cost-effective, scalable, and intuitive to multiple levels of the technology organization.

This chapter unveils one of the essential skills needed by a software architect: the ability to provide architectural perspectives for a project.

Architectural Perspective Defined

Perspective is the ability to step back and view architecture from many different vantage points. Each perspective is not necessarily fully accurate, but being able to see, analyze, and conceptualize from multiple views gives a holistic view of the landscape.

Knowledge of common principles, adages, and rules of thumb can help you measure the nature of the perspective:

• Does it look right?

• Does it meet the expectations of the customer?

• How does it compare to other architectures?

• What are the differences/variances in what is being perceived?

Viewing architecture from multiple perspectives can give valuable insights into the solution (see Figure 7.1).

Figure 7.1. Architectural perspectives

Architectural Principles

As you develop the architecture for a system, a core set of architectural principles can be used to evaluate decisions that are being made. The principles don’t always have to be followed, but you should have some solid rationale for why you are going in a particular direction.

The Principle of Least Surprise

The Principle of Least Surprise is the concept that the idea or approach being taken would not surprise a reasonably knowledgeable person in the subject area being developed when first encountering this element of the system.

This principle can apply to nearly every aspect of the architecture. It can apply to the domain model, where the nouns that are being used represent entities, and the verbs describe the actions that are being performed. Would the words being used surprise an end user?

It can apply to the visualization of the user interface. For example, does the sequence of actions flow easily and naturally? From a hardware perspective, does the configuration of the hardware represent a pattern that the data center personnel are familiar with? If so, is the pattern named or in common use? Naming patterns can go a long way toward establishing context in architectural conversations.

In some very real sense, this principle could be renamed the Principle of Natural Intuition. When this principle is applied, the users of a system should be able to quickly and intuitively understand what to do and what to do next.

When you are reviewing the architecture and you encounter nonintuitive elements, this is the time to closely evaluate the cause. Sometimes the solution is as simple as renaming items. Other times, it requires a major overhaul. Either way, getting the architecture to have the right fit can make the overall system easier to work on, create fewer issues, and give the users a quality experience that will make them want to come back again and again.

The Principle of Least Knowledge (aka the Law of Demeter)

The Principle of Least Knowledge is a concept about minimizing dependencies. As you are architecting the system, the goal is to strive for proper coupling and cohesion. That is, you want loose coupling for capabilities that are more independent of one another, and you want high cohesion for capabilities that are highly correlated to one another (they should do one thing well).

Establishing these boundaries from the outset makes it significantly easier for the development teams to stand up new capabilities; they will have a clear, well-defined purpose. In a similar fashion, the ability to scale new capabilities will be straightforward. Ideally, the capabilities are self-contained. That is, they have no or very few dependencies on other capabilities within the system.

What you want to avoid is a giant mud ball, one in which everything is dependent on everything else within the system. It is very hard to test, to deploy, to refactor, to scale, or to reuse systems that are tightly bound, such that if you touch one part of the system, another seemingly unrelated part of the system changes.

If you are not extremely diligent, there is a natural entropying of the careful boundaries that were laid between various capabilities of a system as the system progresses through time. When you are first architecting the system, take the time to cluster capabilities that form a cohesive group and likewise isolate capabilities that are not related to one another. As the system ages, guard these boundaries diligently, and you can extend the life of a system for years and years.

The Principle of Least Effort (aka Zipf’s Law)

“In simple terms, the Principle of Least Effort means, for example, that a person in solving his immediate problems will view these against the background of his future problems, as estimated by himself. Moreover, he will strive to solve his problems in such a way as to minimize the total work that he must expend in solving both his immediate problems and his probable future problems. That in turn means that the person will strive to minimize the probable average rate of his work-expenditure (over time). And in so doing he will be minimizing his effort. . . . Least effort, therefore, is a variant of least work.”

George Kingsley Zipf

The Principle of Least Effort has applicability to almost every aspect of software architecture, software development, and software usage. At every stage, we tend to follow the path that is the easiest (requires the least effort). This principle generally points to the idea that the start determines the end, so start well; others will perceive that the path of least resistance is simplicity combined with excellence. It sets the initial system expectations high and enables people to do great things, because that is the way things are done for the project.

When considering changes to the design of a user interface, remember that users will find a certain way to accomplish a task, and they will repeat that pattern endlessly to get the task complete unless there is a significantly easier way to perform it, in which case they will change.

The same is true for architecture: if you find a path to architecting systems that works, you are unlikely to change unless you find a significantly better way. Take the time to find a path to architecting that exhibits the qualities you are seeking and the rest will naturally follow. If you take this approach, the next system and the next system will also likely exhibit those same qualities. The previous architectures will act as templates for all of the work you do.

If you are unable to produce an architecture that you like, look to other architects around you for whom you have a high level of respect and emulate the work that they do. Their work can act as a template for you, and eventually the architectures that you produce will feel natural, and you can innovate with your own brand of architecture. You can look for architects inside or outside your organization. There are many architecture resources available.

The Principle of Opportunity Cost

The Principle of Opportunity Cost is based on the notion that resources are scarce and that every choice that is made has a direct impact both on the choices that were excluded (missed opportunity) and on the value that is not being realized by the choice that was made.

Architecture is fundamentally about weighing choices against one another and pragmatically trying to maximize the overall value of the project for the business. The choice is not only what should be, but what should not be.

By making a more tactical decision now, you may enable the business to save money and make additional investments in other promising areas. Alternatively, the exact same situation may enable the creation of critical infrastructure—a more strategic solution—which in turn will lower the cost of future projects that can leverage the new infrastructure.

As you compare the opportunity costs between multiple options for a project, consider the following:

• What is the right answer? The answer may be that all options are valid.

• Who needs to weigh in on the decision? There are likely many opinions on the matter, but who are the critical stakeholders, and how do you explain the alternatives to them in a manner that is understandable and not unduly biased?

• Have all the critical options been considered? If not, it may be opportunity lost.

• How much time do you have to evaluate the options available? My experience has been that the time frame for producing an architectural approach is very limited, and the limited time in which to come up with a single viable option, let alone multiple options, is challenging.

• Do you have a significant enough view into the product pipeline to know not only what is being requested today, but what is being considered for the next year or two? If you don’t have this kind of insight into product development, your ability to evaluate some of the options for the current project will be very limited.

• Are you willing to put your reputation on the line for architectural infrastructure that may or may not reap a return on investment? What is your gut feeling? Can you sell this?

• Are you willing to say no to the business because of the technical debt that will be incurred because of the tactical approach that would need to be taken to get the project done for the price the business wants to pay?

• How will you answer when your boss’s boss wants you to explain why he’s heard from his peer in the NPD organization that the project costs too much? Make sure you have taken the time to vet the solutions and their costs (not just financial) informally before they are published publicly; corrections made in private don’t get noticed as much.

Saving your development dollars as long as possible, avoiding speculative feature development, and keeping a low burn rate will enable the business to have more resources later once the stakeholders better understand what they want.

Within agile, there is a concept of making decisions at the last responsible moment (see the section on that principle later in this chapter). This idea applies to building what you know while looking to the future to determine what and how you can build the system in a cost-effective manner. The key is to be open to change and let the business know what the impacts of the change are.

The Principle of Single Responsibility

The Principle of Single Responsibility is the concept that a module or capability of the system should have only one responsibility. Keeping a service narrowly defined enables everyone who is using it (including testers) and everyone who is developing it to be well aware of what its intended purpose is.

This narrow definition also helps you name the capability correctly. If you are having a problem naming it, take the time to figure out what is wrong with the name or wrong with the definition of what it is doing. Names matter; each name should clearly state what the item does and should be intuitive. If you have to do a lot of explaining to get people onto the same page about what something does, you need to clarify it.

The Principle of Parsimony (aka Occam’s Razor or KISS)

The Principle of Parsimony means eliminating what is unnecessary; it means defining the minimal assumptions necessary to complete something. The goal of Occam’s Razor and KISS (Keep It Simple Stupid) is to reduce complexity.

The areas of relevance to software architecture are everywhere. The principle applies to the interfaces that expose our software to users, the services that reveal the capabilities of the system, the data structures that represent the information our system manages and maintains, and the workflows that orchestrate a series of complex tasks.

As we add features and capabilities to our architecture, we want to do it in a manner that promotes essential elegance, ease of understanding, and the usability and maintainability of the system being produced. The keyword here is essential; it doesn’t mean eliminating the hard problem or a key differentiator of a capability, it simply means removing the clutter.

A good indication of the level of complexity is whether or not you can explain the item of interest in just a few minutes. If you can’t, take the time to look at what can be removed or what doesn’t belong without removing the value of what is being developed.

From a product development point of view, the minimum viable product serves as another variant of Occam’s Razor. The goal here is to focus on the minimal set of essential features that are necessary to complete the system. Taking this approach will speed development, minimize development costs, reduce time to market, and enable quicker feedback from users.

The Lean Startup has refined the process around the minimum viable product. It utilizes quick iterations with customer feedback to help learn what is essential and to steer the evolution of the minimum viable product.

The Principle of Last Responsible Moment (aka Cost of Delay)

The Principle of Last Responsible Moment means waiting to make a decision until you need to. In general, early and potentially uninformed decisions have the potential to hurt you far worse than waiting to make a decision later. By waiting, you have the ability to allow the problem to more fully reveal itself and have a better sense of all the dependencies and risks involved.

The goal is not to wait indefinitely and cause delays in the project implementation and missed shipped dates, but rather to wait to narrow the options until you are better informed. The key is to weigh the cost of delaying the decision. That is, if you wait, what are the impacts, costs, and risks involved?

One of the most effective ways to mitigate these risks and to help weigh alternatives is to engage in prototyping and proofs of concept. Taking the time to jump in and prototype or POC key areas of risk associated with the various alternatives can help give you the insights needed to ensure that when the last (sometimes referred to as the most) responsible moment arrives, you are able to make an informed decision.

The Principle of Last Responsible Moment can be used throughout the life cycle of a project to help manage micro-level decisions, to enable the business to have better visibility into what the real options are, and to help stakeholders visualize what they are really asking for.

The Principle of Feedback

The Principle of Feedback means making decisions about what to do next using feedback loops to help provide the navigation structure for the decisions. The Principle of Feedback is demonstrated in many different areas:

• Agile and Lean development (the evolutionary development of software through small incremental development with direct user feedback to guide the overall solution)

• Lehman’s Sixth Law (guiding continuous change or system evolution through feedback systems)

• Quality-of-service monitoring (measuring key metrics to ensure SLAs and system performance)

• System optimization (measuring and visualizing the key performance aspects of the system to ensure that the right areas are being optimized; using conjecture in this area usually leads to solutions that are not effective)

• User interface design (directing the attention of the users through visual elements such as contrast and proximity)

• Usability testing (observing and measuring how users navigate and react to your system)

The key to developing systems that are able to evolve to meet the ever-changing needs of customers is to employ the Principle of Feedback.

Architectural Concerns

Architectural principles give us a means of evaluating decisions to validate that they are in line with our overall goals for the project and for the technology organization. Architectural concerns are different perspectives of the system often referred to as the “-ilities.” These concerns enable us to consider very narrow dimensions that are typically nonfunctional elements of the system but are critical for the system to behave properly.

Availability

Availability is the notion of how available your system needs to be or conversely how much downtime your business is willing to accept. The answer is often directly related to how much revenue or expense impact there will be if the system is down for some period of time or to what the reputational impact of the system not being available is.

It is not uncommon for the business to initially say it wants 100% uptime; more uptime sounds like a good idea, so why not have a lot of it? This is usually the case until the stakeholders begin to understand the costs associated with having a truly 100% uptime requirement. There are always situations that will force some level of downtime, whether due to maintenance or some form of system failure. The key questions are:

• What amount of time is the business willing to accept for the services to be unavailable?

• How much is the business willing to spend to meet its service availability requirements?

• Do you have or does your hosting provider have the operational staff to support the service availability requirements you are seeking?

• Do you have or does your hosting provider have the operational tools and monitoring in place to detect service unavailability?

• When the service is determined to be unavailable:

• What are the processes and procedures to begin a recovery process?

• Are these processes automated, manual, or a mix of the two?

• How much time does the person responsible for a manual recovery process have to get the job done?

• What are the validation steps that are required once the service has been restored?

• What are the notification and auditing requirements for when an availability issue arises?

• Is root-cause analysis required for determining what the root issue was?

• Are you required to have a mitigation plan to avoid the issue in the future?

• How quickly can you recover from downtimes?

• What mechanisms can you put in place to mitigate a lack of service availability?

• What types of problems are you trying to protect yourself from?

• Storage full. On the surface this one seems silly, but I have seen systems become unavailable due to storage becoming full. The question here is what processes need to be in place to prevent this from occurring. It could be something as simple as monitoring storage full percentages in conjunction with knowing the answers to these questions:

• How fast does the storage fill up?

• Who needs to receive an alert in order to resolve the situation?

• How long does it take to expand or replace the storage (does it need to be ordered, is there additional storage on standby that simply needs to be allocated and made available)?

• Does the data on storage lose value with age? Are these log files that are okay to purge within a specified period of time?

• Storage failures. These could potentially be handled by something as simple as ensuring that this storage is replicated to a separate storage device.

• Server failures. These may be able to be mitigated by clustering servers or by load balancing servers. In either case, you basically have a redundant server or servers that can do the equivalent job if the other server is not available.

• Maintenance windows. These could be handled by simply having a scheduled system outage or a failure over to other hardware.

• Power outages. These can be dealt with by having backup power whether through battery or power generation. The big question is how long you can make this last in a real emergency.

• Site outages. If the site where your servers are hosted goes out of commission, what do you do? Do you have a second or third site that is significantly far away that can act as a backup site? How does this backup site stay in sync? How much data loss are you willing to tolerate if not all of the data was synchronized in time?

• Site loss. Is having a complete site loss acceptable? It might be extremely rare, but what is the impact to the business? Do you have another site that can be quickly or dynamically switched to?

• Software compatibility issues. Do you have lower environments that can be used to test and verify software compatibility?

• Are you contractually obligated to provide a certain level of availability? Be cautious about what you allow the business to specify as an availability requirement and imposing any financial penalties for missed SLAs until you have had an opportunity to fully understand what it will take to meet those obligations. It may cost the business significantly more than it is willing to invest.

Scalability

Scalability enables a system to gracefully respond to the demands that are placed upon it. These can range from storage I/O, to database access, to CPU utilization, to memory utilization, to app server farms, to network utilization. The nature of the application determines what will get stressed out. It is not uncommon to fix one scalability issue only to have another hiding behind it.

The challenge is to understand the nature of the demand that will be placed on the system. It has been my experience that most people incorrectly predict what areas of the system to optimize without testing and detailed monitoring in place to validate the system behaviors that are observed.

When you are first designing the system, you need to determine if you are planning to scale up (buy bigger hardware) or scale out (have multiple sets of hardware that can respond to the same requests). Generally speaking, a scale-out approach is more cost-effective. It will allow you to start out small and add system resources as the demand for the system’s capabilities increase over time.

There are a variety of areas to take into consideration when you are working toward building a system that is capable of scaling to your product’s needs:

• How many users (online and batch) will concurrently access the system?

• How much data will the system be able to manage?

• How many read/write operations per second does the data store need to handle?

• What is the peak concurrent access to the system?

• How much data can be cached to minimize the depth within the system that the requests need to travel before being responded to? Can data be cached outside the system in a content distribution network (CDN) to help keep traffic away from the site? Consider if the content has a significant hit rate (is it worth caching)?

• Is data replication required for the system? How long is it acceptable for the data synchronization to take place?

• How much logging and eventing are required for the system to support the operational needs of the system for immediate as well as future system performance analysis?

• Are there areas of data contention?

• Are there CPU-intensive operations?

• Are there long-running operations?

• How do you plan to measure usage of the system?

• Do you plan to meter services to throttle excessive usage?

• Do you have the ability to auto-provision additional servers to meet demand?

• Can you schedule batch operations to occur at nonpeak times?

Anytime a system resource exceeds 80% utilization, you need to consider some kind of operational warning to give the operations team a chance to find ways to remedy the situation. If it goes beyond 90% utilization, a more urgent notification needs to be sent to the operations team. Ideally, key system resources and error rates are monitored over time and presented in a graphical manner to both the operations team as well as key stakeholders. This gives everyone a chance to keep track of system health and to respond accordingly.

The key to scalability is to test and validate that your assumptions about the system’s behavior are correct. When you are testing, you want to drive the system past its limits to find out where the breaking points are and to find out how the system fails under load. If it does not fail gracefully, look for ways to protect the system.

Extensibility

Extensibility enables a system to be easily added to or changed. From a business perspective, the ability to add to, modify, or change certain aspects of a system quickly and easily can be a critical factor in the ability to scale revenue associated with the system.

Extensibility can include items such as

• Handling deployments to diverse geographic locations

• Enabling alternative styling and branding of the user interface

• Enabling the user interface to be adjusted according to client needs

• Modifying or customizing system capabilities/functionality

The key to handling extensibility is to listen closely to the business early on during the ideation phases and actively listen for areas where the business may want to be able to alter the behavior of the application to address customer needs. Typically, a variety of design patterns can be employed to enable the changes in system behavior or presentation without significantly affecting the architecture or incurring heavy development costs when the requests for change come from the business.

Repeatability

Repeatability is the ability of a system to behave in a consistent manner. This consistency of interaction between the user and the system is what builds trust. It is not uncommon for “new and improved” systems to fail to gain adoption in the user community because this trust factor is broken.

Features that on the surface appear to be less than ideal and consequently appear to be great candidates for change to the system designers may in fact have gained widespread adoption in the user community, and even though they are not perfect, their flawed state is highly useful and “loved” by the users, who are not seeking change.

The notion of repeatability within a system is paramount for setting user expectations.

Compatibility

Compatibility is the ability to introduce nonbreaking changes into the system or minimally a grace period when old functionality is still available while the new or changed capability is rolled out and being adopted.

Compatibility can often be achieved by supporting versioned APIs or historical versions of a system. Eventually these older versions can be deprecated or dropped from support. Providing compatibility with the past allows your user base to find a convenient time to make the required changes within their systems to upgrade to the new versions.

From an architecture perspective, laying changes out in a roadmap can inform your user community of coming changes and allow them to prepare and plan for the changes in their upcoming releases.

This level of transparency with your user base can go a long way toward establishing trust and cultivating long-term relationships. Users will know that their investments will not be quickly thrown out the window if they choose to partner with you and have guarantees of long-term support.

Sustainability

Sustainability is the ability to keep the architecture relevant through change without causing unintended entropy within the system. It goes beyond maintainability in that the intent is to enable continued growth and evolution, not just prevent a degradation of current capabilities.

Sustainability is best achieved by maintaining a proper separation of concerns and not allowing a slow entanglement of capabilities that eventually lead to a large mud ball. Enabling these changes through configuration, inversion of control, and independent deployment of new capabilities leads toward a sustainable system.

Sustainability is essential to the long-term health of the business and helps maximize the return on investment made in technology.

Security, Disaster Recovery, Business Continuity, and Open-Source Licensing

For more information on these topics, see Chapter 8, “Governance.”

Third-Party Integration

As you consider integrating with third-party solutions, you need to look closely at their solutions with respect to the architectural concerns discussed previously. Your customers will expect the same level of service from third parties as they do from the rest of your offerings.

Your business partners may be extremely excited by the possibility of adding a new capability to their portfolio and are likely not to be focused on the architectural concerns; they just expect everything to work out. Make sure you have an opportunity to see the contracts with the third-party providers before they are signed to ensure that the appropriate language is in place to enable everyone’s success.

Architectural Communication

The architectural principles and architectural concerns help guide architects in the development and evolution of an architecture, but it is through active communication that the architecture comes to life.

This communication often takes place as whiteboarding sessions, where the architecture is diagrammed and key aspects of the architecture are discussed. Developing a set of common architectural artifacts can serve as a long-term communication tool for the organization.

Generally speaking, the most effective way to communicate architecture is through pictures and diagrams. There are a variety of different vantage points from which to view the architecture. Typically, these vantage points are from the perspective of key consumers of the architecture.

Domain Model

The domain model is usually developed first in the ideation and discovery phases of a project when it is critical to discover the language of the end users, that is, the nouns they use to describe things and the verbs they use to describe the actions related to the nouns. The model can form the basis of a common language with which to talk to customers, new product development, marketing, sales, and technology. Using the “native” language of the domain can help form natural relationships and cardinality; various parts of the system will naturally work together even if the design teams of the different parts of the system don’t work that closely together.

Process Diagram

A process diagram is used to show the flow of work. It can represent many different aspects of the system that is being developed. A process diagram typically shows the key steps that users take to do their work and their interactions with the system. It gives a sense of where key decision points are within the flow as well as what parts of the work will be automated (controlled by the system) and what parts of the work will be performed outside the system, whether manually or by another system.

Process diagrams can also be used to lay out

• How builds and deployments will work

• How migrations from legacy systems to new systems will occur

• How batch workflows will work and how error conditions will be handled

Key considerations for process flows include the following:

• Where does the process begin?

• What are the prerequisites for the process to begin? For each step to occur? For the process to be considered complete?

• What are the postconditions that need to be considered?

• What are the critical decisions within the flow that will require different actions based on the outcome of each decision?

• How will error conditions and exceptions be handled?

• What are the transitions of work between various actors and roles?

• What subprocess flows need to be created for a deeper level of understanding?

The type of diagram shown in Figure 7.2 may not be produced by the architect, but it is essential to understanding what the user is attempting to accomplish when using the system. If a business analyst is not available to create one, taking the time to produce some basic process flow diagrams can significantly improve your and the project team’s understanding of what needs to be built.

Figure 7.2. Basic process diagram

From an architecture perspective, showing the basic flows of processes can help you understand the sequencing that needs to occur within the solution. Showing decision points and alternative flows can also help inform key aspects of the workflow.

Context Diagram

A context diagram is used to help define the boundaries of the system. It can help with scope discussions to give a visualization of what areas the system will or will not be responsible for managing. Establishing these boundaries early on can help avoid misunderstandings and help clarify the intent of what you are trying to accomplish.

During the life span of the context diagram, the boundaries that define what is in and out of scope may change, but the key outcome is to get everyone on the same page. The diagram may change from release to release as the capabilities of the system expand.

User Interface Mock-ups

User interface mock-ups, even if they are wrong, are extremely important for understanding what the business is looking for. Requirements documents, epic-level user stories, and all other textual forms of specifications for what the business desires to be built typically fail to adequately convey the nuances of what is being requested.

The form of the mock-up doesn’t matter so much; it could be wireframes, it could be sample HTML pages, it could diagrams on a napkin. The key is to begin expressing visually what is desired. The visualizations will spark significantly deeper conversations and reveal nonverbalized dependencies between capabilities and potentially with other systems that were not stated in the textual descriptions.

Early on, before the project is formed, not all of the details are going to be known or fully understood, and they shouldn’t be. The goal is to find out the direction in which the business wants to go and approximately the types of capabilities that are desired. By the time the project completes, the set of capabilities desired is likely to have changed as the business learns more about what it actually wants—as the business people go out and interact with customers and get feedback on the potential direction things are heading.

The business will want to modify its course to align better with customer expectations. This is a great thing, except that it may feel as if you are following a rabbit trail. Changes earlier in the project are easier to accommodate, whereas after a significant portion of the system has been built, changing directions can become expensive.

Logical Architecture Diagram

The logical architecture diagram describes the key components of the system. A typical diagram takes a separation-of-concerns approach where there is a section relating to the user interface, a section for the core system capabilities (this is where most of the business rules exist), a section for the persistence layer (your data storage mechanism), and a section for any crosscutting concerns such as security, logging, reporting, and so on.

This diagram typically has a very functional bent to it (see Figure 7.3).

Figure 7.3. Logical architecture diagram

A logical architecture diagram can take many forms. The intent is to show key logical groupings of the architecture and show some of the separation of concerns. The logical architecture can also guide the planned implementation, including the various design patterns that may be considered.

Executive Overview Diagram

An executive overview diagram, a high-level conceptual diagram for executive stakeholders, should basically have five boxes or fewer. You need to significantly raise the level of abstraction for the system under consideration. You should include basic descriptions of the boxes and answers to a few questions that you expect to be asked, such as what other alternatives were considered. The executives need to be able to understand the diagram in less than two minutes; it needs to be intuitive, and they will naturally dive into whatever areas of detail they sense are not solid or have issues.

Be prepared for them to dive in two to four layers deeper than what is shown at the highest level. Be prepared for them to find the area of vagueness where all the details have not been figured out; they have a natural instinct for finding these areas.

Hardware Environments Diagram

The hardware environments diagram is essential for interacting with the data center folks. These diagrams will help answer the following questions:

• What environments will the project support?

• Sandbox (aka development lab)

• Development (aka continuous integration)

• Quality assurance

• Demo

• User acceptance testing (QED), typically sized near production

• Production

• Who has ownership of each environment—development group, data center operations, networking, database admins?

• How much of each type of hardware is needed? Will this be physical hardware, virtual hardware, or cloud-based hardware?

• What is the configuration of each type of hardware? Are the servers clustered? If so, how? What servers need access to which storage? How much internal storage is required? How much network-attached storage (NAS) is required? What operating system is required? What type of licensing is required?

• What purpose does each type of hardware serve? Are the servers app servers? Database servers? Network switches? NAS filers?

• What are the delivery time frames of each type of environment?

• For each type of hardware and environment, what groups are to be notified when issues arise or maintenance is required?

• What naming conventions will be specified for the hardware?

• What networks do the servers need to be connected to?

Sometimes to aid in the understanding of the hardware environments you are trying to stand up, taking the time to name the pattern of the hardware configuration can make the capital purchasing much simpler. People who are reviewing the purchase will recognize the pattern name and quickly understand the approximate cost and operational needs of the request. This can make reviews of the purchase go much more quickly and require less documentation and explanation to get the purchase approved.

Risks, Assumptions, Issues, and Dependencies (RAID)

One of the key areas of documentation for an architect to produce is the risks, assumptions, issues, and dependencies (RAID) associated with a project (see Figure 7.4).

Figure 7.4. RAID

RAID is an effective tool for ensuring coverage of key executive concerns and those of a wider audience.

Later on, when the project is midway through execution and something goes horribly wrong, the architect is usually one of the first people called in to help determine why this occurred and why the problem wasn’t recognized earlier. This usually invites executives to get involved. The best time to prepare for this is when the project is getting started. This is the time to clearly call out the risks, assumptions, issues, and dependencies.

Risks

Risks are the events that have a reasonable likelihood of occurring and may have a significant impact on the architecture or success of the project. When considering the architectural risks, consider the following:

• What risks may cause the project to be delayed or not delivered?

• Are there software development skills that are not currently employed in your areas?

• Are new technologies required for the project that your company or area is not familiar with?

• Are there specific contracting needs for the project?

• Are there scaling needs that the business is not willing to pay for?

• Are there lower environment needs that will not be fulfilled?

• Are there testing efforts that will not be funded?

• Are significant business risks being introduced?

Documenting risks lets stakeholders know the key areas of uncertainty that may derail a project. It allows them to develop risk mitigation plans in the event that a risk becomes a reality. It also serves as a mechanism of full disclosure and transparency that help build trust.

Assumptions

Assumptions are the prerequisites for your architecture. They are the things you believe to be completed or true. As you build and document your set of architectural assumptions, consider the following:

• What assumptions are you making about the project?

• Are you assuming that

• You can successfully develop some new capability?

• Certain groups will do particular parts of the work?

• Certain refactoring will occur within an existing system?

• Certain integrations will be required or will explicitly not be supported?

• Some research and development needs to occur?

Your documented assumptions will help level-set people’s thinking about the architecture and will serve as an issue resolution mechanism later on when problems arise.

Issues

Issues are the outstanding questions that have not been resolved. These include:

• What areas of the architecture have not been finalized?

• Are there areas of technology that have not been spiked, contain areas of concern, or have known problems?

• Are there contractual issues in play?

• Has a key resource recently moved to another part of the company?

• Is the deadline for delivery overly aggressive?

It is critical to identify issues in your architectural documentation. Doing so will give those who are working on a project a sense of what areas of the architecture have not been resolved and may still need to be dealt with.

Dependencies

Dependencies are the items, tasks, or projects that your architecture is dependent upon or that are dependent on your architecture. As you identify your architectural dependencies, consider the following:

• What projects are you dependent on for your project to complete? If you call out a dependency like this, you may want to consider adding the cost of the portion of the project you are dependent on to your estimate. It is not uncommon for dependent projects to be late, to not complete the feature that you need, or to change the feature that you need in a manner that renders it useless. The alternative solution that you provide may be a tactical solution, but it will be financed and you will have the opportunity to complete on time instead of waiting or being stuck with nowhere to go.

• What licensing agreements are you dependent on to provide needed functionality?

• What purchases or other procurements are needed?

• What business arrangements are needed?

• What hardware needs to be purchased or operationalized?

• What infrastructural software needs to be operationalized?

• Is software integration with specific tools or services required?

Basically, dependencies are anything that you need that will block you from delivering the project if you don’t have them.

Dependencies need to be very clearly stated and made visible to the executive staff. This will help them manage the dependencies for you on the outside chance that the dependencies get off track. They may be able to apply the necessary influence to enable your dependencies to deliver. After all, it will be in your management’s best interest to make sure your dependencies deliver and your project delivers as promised.

Bringing It All Together

Following the architectural principles, dealing with architectural concerns, and developing effective architectural artifacts can help you deliver solid architectures for the business.

Don’t let one vantage point drive you to an extreme. These are not laws; they are for guidance. For every rule there are conditions that justify breaking it.

Summary

The road to architectural perspective begins with

• Knowing and understanding architectural principles

• Knowing and understanding key areas of architectural concern

• Creating architectural artifacts to bring clarity to what is being created

Having an architectural perspective on a project can result in a broad understanding of it. It can help raise and clarify key risks, assumptions, issues, and dependencies to help enable a smoothly running project where both the business and technology have a common understanding of what is being produced.

References

Bass, Len, Paul Clements, and Rick Kazman. 2012. Software Architecture in Practice, Third Edition. Addison-Wesley.

Clements, Paul, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, and Judith Stafford. 2011. Documenting Software Architectures: Views and Beyond, Second Edition. Addison-Wesley.

Janert, Philipp K. 2013. Feedback Control for Computer Systems: Introducing Control Theory to Enterprise Programmers. O’Reilly Media.

Poppendieck, Mary, and Tom Poppendieck. 2003. Lean Software Development: An Agile Toolkit. Addison-Wesley.

Reinertsen, Donald. The Principles of Product Development Flow: Second Generation Lean Product Development. Celeritas Publishing.

Rozanski, Nick, and Eóin Woods. 2011. Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives, Second Edition. Addison-Wesley.