Introduction to the Architecture Decision Canvas: Making better architecture decisions together

Table of Contents

• Yet another canvas?
• Motivation
• What is the Architecture Decision Canvas?
• What is the basic structure of the Architecture Decision Canvas?
• The Architecture Decision Canvas example in action (real world example)
• Final thoughts
• Downloads

Yet another canvas?

You read correctly - I'm introducing another (architecture) canvas 😄.

The title reminds me of the funny comic Agilé 👇

Yes, there are already some architecture canvases for certain topics, e.g.

• Architecture Inception Canvas
  • An Efficient and Collaborative Way to Define your Software Architecture Playground
• Architecture Communication Canvas
  • The shortest possible description of your architecture
• Tech Stack Canvas
  • Create, document, and communicate your product's tech stack

Let's leave the "The Canvas Canvas" fun aside and get into my idea and evaluate whether the new Architecture Decision Canvas can bring you added value in your daily work as a software architect 😃.

Motivation

As a software architect, I am often in a situation where I have to clarify difficult architectural issues with several teams.

• Which frontend architecture style should we follow?
• Should we use Http with a REST approach or use gRPC?
• Should we follow a serverless approach? Is it worth taking a look?
• Should we use Keycloak, Okta or Zitadel as IdP?
• Should we introduce a process engine to orchestrate our services?

As I'm not a benovelent dictator architect, I naturally work with the whole team (or sometimes even across teams) to make the right architectural decisions when it comes to an overarching decision. I like more the Architecture Owner, Architecture Agents or Architecture Democracy approaches.

Such architecture-related questions often have far-reaching consequences for the success of the software initiative.

It is also important that the right people are entrusted with the decision, which people are consulted and which people are affected by the decision. Therefore, the composition of the relevant people often plays a decisive role in architecture decisions.

It's not just about making the right choice - it's about making the right choice transparently, cooperatively and strategically.

It is therefore very important that these questions are answered in a structured and comprehensible way. There are already many tools and techniques that support a structured template for architecture decisions capturing and recording. 👇

The current landscape of tools and techniques for capturing architectural decisions

There are various techniques and tools that support a software architect in his or her work.

Architecture Decision Records (ADR) technique

An Architectural Decision Record (ADR) documents critical architectural decisions in software development and describes the reasons, context and consequences.

ADRs were introduced by Michael Nygard in 2011 and are used to retain important knowledge about the software product to enable informed decisions and continuity. This approach helps both new and existing team members to understand and re-evaluate important architectural decisions.

ADR templates

There is a whole range of different templates for recording architectural decisions (you can find the whole list here):

• Architecture Decision Record template by Michael Nygard
• Architecture Decision Record template by Jeff Tyree and Art Akerman
• Architecture Decision Record template by EdgeX
• Architecture Decision Record template by Paulo Merson
• Markdown Architecture Decision Records by the MADR project

ADR tools

There are several tools and frameworks that support the recording, management and maintenance of Architectural Decision Records (ADRs).

Here are a few notable ones:

1. ADR Tools by Nat Pryce: A command-line tool that helps in managing ADRs, allowing for easy creation and maintenance of ADRs within a project's repository.
2. Log4brains: A static site generator and a knowledge management tool designed for ADRs. It allows for creating, viewing, and managing ADRs in a more interactive and user-friendly interface.
3. adr-manager: A web-based tool for managing ADRs, providing a user-friendly interface for creating, editing, and viewing architectural decisions.
4. pyadr: CLI to help with an ADR lifecycle process (proposal|acceptance|rejection|deprecation|superseding) based on Markdown files and git.
5. madr-tools: Node.js CLI tool to create and manage Markdown Architectural Decision Records (MADR)

...and what is missing in this ADR space?

For me, the decision-making process in software architecture is an iterative and collaborative team effort. That's why I need a tool or a technique that enables a truly collaborative approach.

Since I also missed the collaborative part in the initial architecture work, I developed the Software Architecture Canvas, also known as the Architecture Inception Canvas, in the arc42 community.

The same now applies to collaborative, team-based decision-making in architecture.

This is where the Architecture Decision Canvas (ADC) comes into play.

What is the Architecture Decision Canvas?

The Architecture Decision Canvas (ADC) is a visual and structured approach to guide teams through the critical decision-making process in a collaborative way.

It provides a comprehensive template for discussing, communicating and determining specific architectural decisions.

With the Architecture Decision Canvas you can:

• Collaborate effectively on specific architecture issues and problems
• Understand the impact of decisions on different stakeholders
• Evaluate options, resulting risks and trade-offs
• Ensure strategic alignment with quality goals and other forces
• Communicate decisions and the underlying options effectively

The idea of the Architecture Decision Canvas (ADC)

The idea of the Architecture Decision Canvas is inspired by the Business Model Canvas, Lean Canvas and, of course, the Software Architecture Canvas (😄), which have long been used for focused and structured brainstorming and collaboration.

Based on these successful canvases, ADC applies the same principle to the special requirements of the decision-making process in software architecture.

What is the basic structure of the Architecture Decision Canvas?

Let's break down the Architecture Decision Canvas.

Basically, the canvas can be split into the following areas:

What is the problem?

The first step in any architectural decision-making process is to elaborate and describe the specific problem and establish a context.

Try to describe the problem domain. This can be done well collaboratively.

Why is the decision important?

Start with a why.

Why is the decision for this problem statement important right now?

What are the risks, if we don't decide anything?

What are the decision drivers like concrete quality goals or other decision drivers? (e.g. organisational or technical constraints)

Who is involved or affected?

Often for certain architecture decisions there are a lot of different interested parties.

Who are the deciders?

Who should be consulted?

Who is affected by decision?

How can we tackle the problem?

Often you consult different options before you do a decision. So try to elaborate different options before you take a specific decision. Especially work out the good and bad consequences on the specific options.

The Architecture Decision Canvas explained

Let's go through each section of the Architecture Decision Canvas and discuss the purpose of it.

Problem & Context

This section describes the architectural challenge and the problem area in which it arises.

It’s important to provide enough background so that everyone working on the architectural question understands the situation that triggered the need for a decision.

A well-defined problem lays the foundation for a clear and structured decision-making process.

Risk, if not decided

Here you describe the risks of inaction.

What could go wrong if no decision is made?

Will technical debt pile up, will the team be blocked or will business opportunities be missed?

Will there be de facto decisions?

This section emphasizes the urgency and helps stakeholders understand why a timely decision is important.

Define the implications of not making a decision, or making the wrong one?

This area helps you map out the potential pitfalls.

Decider(s)

This part lists the persons or roles responsible for the final decision.

Naming the decision-makers ensures accountability and avoids confusion about responsibilities.

Consulted

In this section, you name the experts, stakeholders or teams whose contributions should be taken into account.

They may not be the decision-makers, but their knowledge and perspective are essential for an founded decision.

Involving them helps to reach a consensus and avoid blind spots.

Affected

Here you specify who will be affected by the decision. This could be developers, operations teams, product managers or even end users.

Knowing those affected promotes empathy in the decision-making process and encourages proactive communication.

Considered Options

Here we describe the different solutions or approaches that have been considered to solve the problem.

Each option should be accompanied by a brief explanation of its advantages and disadvantages. This makes the process more transparent and documents that several options have been carefully examined.

Quality Goals and other Decision Drivers

This part describes the most important quality goals and other factors that influenced the decision.

This can include goals such as scalability, performance and / or maintainability.

By making it clear what is most important, we steer the decision in a direction that is geared towards long-term success.

Decision Outcome

In this section, we indicate which option was ultimately chosen and why.

It is important to explain the reasons for the decision so that future teams can understand the context and reasoning. This prevents confusion and unnecessary re-evaluations.

Consequences

Finally, we summarize the expected positive and negative consequences of the decision.

This includes both technical and organizational implications. Understanding the trade-offs helps manage expectations and prepares the team for implementation and follow-up.

The Architecture Decision Canvas Example in Action (a real world example)

Let's look at the following real world example 👇

A software company is faced with the challenge of creating a uniform look and feel (UI) for its products with a common corporate brand.

Problem & context

The marketing team realised that the appearance of the various products was not consistent.

To be consistent with the corporate brand, a unified approach to user interface design is required.

Risk, if not decided

If no decision is made, each product team will continue to solve UI/UX issues and its ui components independently, making future changes difficult and inconsistent across the product landscape.

Deciders

The members of the Architecture Board are responsible for making the final decision on how UI standardization should be approached throughout the company.

Consulted

Key people such as the CTO, front-end architects and designers were consulted to gain insight into feasibility and design considerations.

Affected

All product teams are affected by this decision, as it impacts how UI/UX will be implemented across their applications.

Considered options

Three options were evaluated:

• building a custom UI library
• buying and customizing a third-party library
• or allowing each team to build their own UI independently.

Quality Goals & Other Decision Drivers

The main goals are to ensure a consistent and branded UI/UX and make it easy to maintain and update the UI theme across all products.

The future component ui library has to support React as a frontend framework.

Decision Outcome

The architecture board chose to buy a third-party library and customize it to create a common theme, balancing speed and consistency while avoiding heavy internal development overhead.

Consequences

• The good: faster time to market and access to mature UI components.
• The bad: limited design flexibility.
• What’s open: deciding who owns and maintains the customized theme.

Final Thoughts

The Architecture Decision Canvas (ADC) is more than just a template - it is a collaborative companion for every software architect on the way to creating coordinated software products

It guides software teams through the fog of architecture decisions and ensures that decisions are not just made, but made with intention, understanding and foresight.

When you use ADC in your software initiatives, you get a collaborative tool. It's a narrative that not only captures where you've been, but more importantly, gets you where you need to go.

The ADC is not just a tool, it's a mindset — a commitment to excellence and strategic thinking in architectural decision making in software product development.

Downloads