Book: Software Architecture and Decision-Making

6 min readDec 15, 2023

The Problem

What are the common causes of architectural/ design mistakes?

Over two decades, I’ve played pivotal roles in shaping the architecture and code of notable projects like Apache Axis2, Apache Airavata, and WSO2 (Siddhi, Choreo) products. These projects are trusted by Fortune 500 companies and organizations worldwide, including banks, unicorns, and governments. Chances are you have used many of those systems. Over time, I have sat on many architecture reviews and war rooms to solve critical challenges.

Those projects gave me a front-row seat to numerous architectural decisions and their outcomes, which convinced me that most software design mistakes do not happen due to a lack of technical expertise.

Get the Book (Amazon)

Instead, most design mistakes stem from a lack of judgment. Most mistakes happen because two of our design techniques, tools, or abstractions get in each other’s way or because we went overboard with one. In these cases, I observe leadership challenges rather than technical challenges. This is primarily because decisions in software architecture are deeply influenced by the specific context. For instance, if you inquire about the best approach regarding an aspect of software architecture (e.g., portability, microservices), the most accurate response is often “It depends.”

Software Systems => Uncertainty

This ambiguity arises due to the inherent uncertainties within software systems. They come in many forms:

Our grasp of the use case, or the problem we’re addressing, is often incomplete.
Our comprehension of the business context surrounding the problem, such as timelines and team dynamics, is only partial.
Both the use cases and the business context are subject to change over time.
Understanding these use cases and the business context varies among team members, with each person having only a partial view.

The good news is that when designing systems, an architect has various tools such as Loose Coupling, Abstractions, Iterative Development, Experiments, and Feedback Loops at their disposal to manage uncertainty:

Uncertainty demands Leadership

However, each technique for managing uncertainties in system design also incurs its own costs. There are numerous instances where the most prudent decision is to overlook certain uncertainties because addressing them could introduce greater risks or entail excessive costs (e.g., making some applications portable across the cloud). An architect or leader must evaluate the risks associated with these uncertainties against the costs of addressing them. Making a judgment call in this context is crucial for moving forward effectively and efficiently.

Handling uncertainty encapsulates the essence of leadership.

Leadership, in my view, is about managing Uncertainty, bringing Order to chaos, providing hope for a better future, and making Progress.

Often, people are inclined to follow those who demonstrate an ability to handle uncertainty. This applies to technical leadership, too.

The Book

The book “Software Architecture and Decision Making” delves into this concept, particularly discussing how to “assess the risk associated with uncertainties against the costs of handling those uncertainties, make a judgment call, and make progress.” This approach is central to effective leadership in the field of software architecture.

Get the Book (Amazon)

There are many books on leadership and many more on architectural principles. The intersection of leadership and architecture are seldom addressed, yet they are vital. Leading a product goes beyond mere technical expertise; it encompasses team management, uncertainty navigation, and strategic decision-making.

The Five Questions and Seven Principles (5Qs & 7Ps)

The book proposes five questions and seven principles. The questions let us asses uncertainties that are not apparent, and the principles help us make the judgment call on how to handle them.

Five Questions

Q1: When can we rewrite the system?
Q2: When is the best time to market?
Q3: What is the skill level of the team?
Q4: What is our system’s performance sensitivity?
Q5: What are the hard problems?

Seven Principles

P1: Drive everything from the user’s journey.
P2: Use an iterative thin slice strategy.
P3: On each iteration, add the most value for the least effort to support more users.
P4: Make decisions and absorb the risks.
P5: Design deeply things that are hard to change but implement them slowly.
P6: Eliminate the unknowns and learn from the evidence by working on hard problems early and in parallel.
P7: Understand the trade-offs between coherence and flexibility in the software architecture.

In the interest of time, I won’t delve into extensive detail about each principle. For more details, please refer to the Slidedeck or consult the sample Chapter 2.

Outline of the Book

Chapters 1 and 2 of the book delve into the five questions and seven principles. Chapters 3 and 4 provide background on performance and user experience (UX), areas that often receive less attention, even though they are crucial in the decision-making process.

Then, the book first tackles macro architecture — discussing the decomposition of the system into components and addressing challenges like coordination, state consistency, security, scalability, and high availability. It then shifts focus to crafting individual services (components) and constructing a stable system. The book examines how to apply five questions and seven principles to make decisions within each chapter.

Finally, Chapter 13 synthesizes all these elements, bringing everything together.

The Learnings

The book aims to impart the following learnings:

Build an appreciation for the significance of judgment in architectural decision-making
How to approach the design systematically, first at the macro level and then at the individual service level?
How to use default choices for many design decisions and know when to deviate from those decisions?
How to use five questions and seven principles to guide their choices?

The book frequently references examples from notable technical leaders, such as the Wright Brothers and Kelly Johnson. These examples illustrate key concepts and demonstrate how effective leadership and decision-making have been pivotal in the success of these historical figures.

You can find more details in