Introduction to the Architecture Decision Canvas: Making better architecture decisions together架构决策画布（Architecture Decision Canvas）简介：共同做出更好的架构决策

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é 👇这个标题让我想起了那部有趣的漫画《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?我们应该使用基于 REST 的 HTTP 还是使用 gRPC？
• Should we follow a serverless approach? Is it worth taking a look?我们应该采用无服务器（Serverless）架构吗？值得尝试吗？
• Should we use Keycloak, Okta or Zitadel as IdP?我们应该选择 Keycloak、Okta 还是 Zitadel 作为身份提供商（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.由于我不是那种独断专行的架构师，在涉及全局决策时，我自然会与整个团队（有时甚至是跨团队）合作，以做出正确的架构决策。我更倾向于架构所有者（Architecture Owner）、架构代理（Architecture Agents）或架构民主（Architecture Democracy）的方法。

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架构决策记录（ADR）技术

An Architectural Decision Record (ADR) documents critical architectural decisions in software development and describes the reasons, context and consequences.架构决策记录（ADR）用于记录软件开发中的关键架构决策，并描述其原因、背景和后果。

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 由 Michael Nygard 于 2011 年引入，用于保留有关软件产品的重要知识，以实现明智的决策和连续性。这种方法有助于新老团队成员理解并重新评估重要的架构决策。

ADR templatesADR 模板

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 NygardMichael Nygard 的架构决策记录模板
• Architecture Decision Record template by Jeff Tyree and Art AkermanJeff Tyree 和 Art Akerman 的架构决策记录模板
• Architecture Decision Record template by EdgeXEdgeX 的架构决策记录模板
• Architecture Decision Record template by Paulo MersonPaulo Merson 的架构决策记录模板
• Markdown Architecture Decision Records by the MADR projectMADR 项目的 Markdown 架构决策记录

ADR tools ADR 工具

There are several tools and frameworks that support the recording, management and maintenance of Architectural Decision Records (ADRs). 有多种工具和框架支持架构决策记录（ADR）的记录、管理和维护。

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.Nat Pryce 的 ADR Tools：一个命令行工具，有助于管理 ADR，允许在项目仓库中轻松创建和维护 ADR。
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.Log4brains：一个专为 ADR 设计的静态网站生成器和知识管理工具。它允许以更具交互性和用户友好的界面来创建、查看和管理 ADR。
3. adr-manager: A web-based tool for managing ADRs, providing a user-friendly interface for creating, editing, and viewing architectural decisions.adr-manager：一个基于 Web 的 ADR 管理工具，为创建、编辑和查看架构决策提供了用户友好的界面。
4. pyadr: CLI to help with an ADR lifecycle process (proposal|acceptance|rejection|deprecation|superseding) based on Markdown files and git.pyadr：一个 CLI 工具，基于 Markdown 文件和 git 辅助 ADR 生命周期流程（提案|接受|拒绝|弃用|取代）。
5. madr-tools: Node.js CLI tool to create and manage Markdown Architectural Decision Records (MADR)madr-tools：用于创建和管理 Markdown 架构决策记录（MADR）的 Node.js CLI 工具

...and what is missing in this ADR space?……那么在 ADR 领域还缺少什么呢？

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.由于我也发现在初始架构工作中缺少协作部分，我在 arc42 社区开发了软件架构画布，也称为架构启动画布（Architecture Inception Canvas）。

The same now applies to collaborative, team-based decision-making in architecture. 同样的情况也适用于架构中基于团队的协作决策。

This is where the Architecture Decision Canvas (ADC) comes into play.这就是架构决策画布（ADC）发挥作用的地方。

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.架构决策画布（ADC）是一种视觉化且结构化的方法，旨在引导团队以协作方式完成关键的决策过程。

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)架构决策画布（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.基于这些成功的画布，ADC 将同样的原则应用于软件架构决策过程的特殊需求。

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.一家软件公司面临挑战，需要为其产品创建具有统一企业品牌的统一外观和感觉（UI）。

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.如果不做出决定，每个产品团队将继续独立解决 UI/UX 问题及其 UI 组件，从而导致未来的变更变得困难，且整个产品布局不一致。

Deciders决策者

The members of the Architecture Board are responsible for making the final decision on how UI standardization should be approached throughout the company.架构委员会成员负责就如何在全公司范围内实现 UI 标准化做出最终决定。

Consulted

Key people such as the CTO, front-end architects and designers were consulted to gain insight into feasibility and design considerations.咨询了 CTO、前端架构师和设计师等关键人员，以深入了解可行性和设计考量。

Affected

All product teams are affected by this decision, as it impacts how UI/UX will be implemented across their applications.所有产品团队都受到此决策的影响，因为它会影响 UI/UX 在其应用程序中的实现方式。

Considered options考虑的选项

Three options were evaluated: 评估了三个选项：

• building a custom UI library构建自定义 UI 库
• buying and customizing a third-party library购买并自定义第三方库
• or allowing each team to build their own UI independently.或者允许每个团队独立构建自己的 UI。

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.主要目标是确保 UI/UX 的一致性和品牌化，并使在所有产品中维护和更新 UI 主题变得容易。

The future component ui library has to support React as a frontend framework.未来的组件 UI 库必须支持 React 作为前端框架。

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.优点：更快的上市时间以及对成熟 UI 组件的使用。
• 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.架构决策画布（ADC）不仅仅是一个模板，它是每一位软件架构师在创建协调软件产品之路上的协作伙伴。

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.当您在软件计划中使用 ADC 时，您就获得了一个协作工具。它是一个叙事，不仅记录了您走过的路，更重要的是，它指引您走向需要去的地方。

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.ADC 不仅仅是一个工具，它是一种思维方式——一种在软件产品开发架构决策中追求卓越和战略性思维的承诺。

Downloads

Architecture Decision Canvas Template | Miroverse架构决策画布模板 | Miroverse

Discover how Patrick Roos does Architecture Decision Canvas in Miro with Miroverse, the Miro Community Templates Gallery. View Patrick Roos’s Miro templates.了解 Patrick Roos 如何在 Miro 中使用架构决策画布，通过 Miro 社区模板库 Miroverse 探索。查看 Patrick Roos 的 Miro 模板。

Miroverse