The Software Architecture Canvas: An Efficient and Collaborative Way to Define Your Software Architecture Playground

In this blog post, I want to introduce you to the Software Architecture Canvas and explain its core elements.

Table of Contents

🎉
The Software Architecture Canvas is now part of arc42!

The story behind it: Interestingly, Gernot Starke and Patrick Roos developed a canvas for software architecture work in parallel: The Architecture Communication Canvas and the Software Architecture Canvas.

Therefore, over the past few weeks, we have created https://canvas.arc42.org/.

Motivation

The situation that probably every software developer loves: the start of building a new system and the resulting technical questions and discussions:

  • Do we take a micro services approach?
  • Functional or object oriented?
  • Do we follow the hexagonal architecture approach?
  • Do we do an event-driven approach with CQRS?
  • Or do we follow a serverless approach?
  • Java, F#, Go or Rust?
  • Azure, AWS or GCP?
  • NoSQL vs. SQL? MongoDB vs. PostgreSQL?
  • Angular vs. React vs. Solid?
  • Docker vs. Podman?
  • Continuous Integration and Deployment Pipelines? GitOps?

A lot of technical questions for technology lovers (like me :-)).

But wait... are these questions even relevant at the beginning of a software initiative?

In my role as Tech Lead and Software Architect, I've been involved with many new software initiatives with product teams.

And it's always the same traps that software development teams first fall into: The need to discuss these fancy technical and low-level architectural design topics.

Yes, I also like to discuss this kind of technical stuff.

But these discussions are useless at the beginning of building a new system, because you have to define your engineering playground first.

If you don't know your playground, you have no chance to argue technical decisions.

Over the years, my experience has been that there are always the same questions that need to be discussed and answered across the product team before you start discussing technical things.

That's why I developed the Software Architecture Canvas, which helps product teams lay the groundwork for software architecture in an efficient and collaborative way.

The Software Architecture Canvas

The Software Architecture Canvas Explained

In this chapter, we'll discuss the core elements of the Software Architecture Canvas.

The structure of the Software Architecture Canvas

The Software Architecture Canvas is divided into three parts:

  • Goals: What should the software do? (green)
  • Solution: How can we achieve it? (yellow)
  • Assessment: How do we evaluate the situation? (blue)
The structure of the Software Architecture Canvas

Business Case: Here's your WHY

If the business needs to make money, there is an economic driver and a business case behind every software initiative. If not, it's a hobby or an NPO project.

And it all start with WHY. - Start with WHY.

A common pitfall is that the development team, or worse, the entire product team, is unaware of the specific economic drivers and business case behind these software initiatives.

As a team member, if you don't know or can't explain the economic driver or business case behind the software initiative, you don't need to proceed. Then you're often unable to define a meaningful playground for your software architecture because you don't know what you're trying to achieve for your business.

In my experience, it's so important that every team member knows the economic driver and can explain the business case behind a software initiative.

Describe the Business Case with the Software Architecture Canvas

With this section of the Software Architecture Canvas, you put the entrepreneurial hat on each team member and empower them to think entrepreneurially.

With this section of the Software Architecture Canvas, you put the entrepreneurial hat on each team member and empower them to think entrepreneurially.

This promotes the intrinsic motivation of each team member and helps in the daily macro and micro decision making in the realisation of the software product.

Functional Overview: This is the most important part on your product box.

As you work out the functional overview of the software initiative as a product team, imagine a product box of your software - what is on your software box?

What does your product box say? This is the basis for the functional overview. (Image Source)

Describe the most important functional requirements at a high level in the Functional Overview part

Think the product box to get the answers to the following questions:

  • What business value does the software deliver?
  • What are the higher-level business functions?

With the answers to these questions, you can describe the key functional requirements at a high level.

Quality goals: The key drivers of architecture

Here you work out the three most important quality goals of the stakeholders for the software system.

Gather the top three quality goals for the architecture

It's important that these quality goals are known by every team member because they shape your architecture.

The standard ISO /IEC 25010 provides a good overview of possible quality attributes of interest.

ISO 25010
Portal sobre la familia de normas ISO/IEC 25000 para la evaluacion de la calidad del producto software. Listado de laboratorios de evaluación acreditados y productos certificados.

Business Context: Explore the context and get the scope

Business context focuses on your system as a black box. Attention is focused on the system's environment and how the system interacts with all external systems within it.

Define the Business Context and the Scope of your System

With the business context, you can identify the communication paths and thus potential technical risks.

It's also a good way to discuss with various stakeholders the scope of the system and the communication paths to various external systems.

When trying to work out the business context, try to identify the users of your system and all neighbouring systems.

In this part, you're to create a business-oriented context view to get a common view of the business scope of the system. So focus on a common understanding and use this part to develop a tool to communicate the system context to other stakeholders inside and outside the team.

This business-oriented scope is the basis for a later technical context. Here you elaborate the center of your software architecture activities.

Organisational and Technical Constraints: Your limitation of freedom

Organisational and technical constraints determine the degree of your freedom to make decisions as an engineering team.

Know your organisational and technical constraints

In this part you work out all the requirements that limit your freedom as a product team in developing the software product.

Organisational constraints

Organisational constraints often include time and money. I've also seen that there are constraints on the methodologies used (such as SAFe, Scrum, ...) or techniques.

Technical constraints

In larger enterprises, there are often a lot of technical constraints. There is often an overarching architecture committee that sets the standards for technology choices. For example, if you decide to build a single-page application, the overarching architecture committee will set Angular as the SPA framework, so there are expertise synergies between teams.

Architectural Hypotheses: Create your first high-level architectural hypotheses based on your current knowledge

Congratulations - you've created your architectural playground. Now you can create your first architectural hypotheses based on your current team knowledge.

Establish initial architectural hypothesis or document architectural decisions already made

Be aware: this is about higher-level architectural assumptions, not micro-decisions like design questions.

Ideally, you can turn your architectural assumptions into draft architecture decision records.

Challenges and risks: What are the upcoming challenges and the resulting risks?

Based on the playground you have created, such as business context and scope, quality goals and constraints, you can capture the upcoming challenges and the resulting risks.

Document the current challenges and risks of the initiative.

It's very important to work this out, evaluate it continuously, and communicate it to the key stakeholders in the system.

This section answers the question of how you evaluate the current situation in relation to the elaborated architectural playground.

Compatibility with techniques for documenting software architecture

After you've done the first iteration on your team with the Software Architecture Canvas, you have valuable deliverables on the Canvas.

So it's time to start documenting your software architecture.

If you need a foundation for writing good software architecture documentation, I recommend The Ultimate Guide to Software Architecture Documentation.

The Ultimate Guide To Software Architecture Documentation
This guide shows you how to write, structure, visualize and manage software architecture documentation in a lean way using appropriate documentation tools.

Software Architecture Canvas vs. arc42 - it's a match!

If you're working with the arc42 template, you can easily switch from the Software Architecture Canvas to your arc42 template.

From Software Architecture Canvas to Software Architecture Documentation with arc42

You can map the following sections of the Software Architecture Canvas to arc42:

Software Architecture Canvas vs. C4 Model

If you work with the C4 Model, you get the first level of the C4 Model, the System Context, with the "Business Context" part in the Software Architecture Canvas.

With the software architecture canvas you get the basis for the first level of the C4 model: The System Context View 

With the High Level Architectural Hypothesis or the first architectural decision, you can probably create the Container View (Level 2).

Software Architecture Canvas vs. Software Architecture for Developers

Simon Brown, in his book "Software Architecture for Developers" advises people to think of the documentation as a guide that provides enough information to get them started and helps them speed up the exploration process.

He recommend to choose from the following ingredients into the guidebook:

  1. Context
  2. Functional Overview
  3. Quality Attributes
  4. Constraints
  5. Principles
  6. Software Architecture
  7. External Interface
  8. Code
  9. Data
  10. Infrastructure Architecture
  11. Deployment
  12. Operation and Support
  13. Decision Log

You can find these recommended parts of the guide on the Software Architecture Canvas, which you can map directly.

With the Software Architecture Context you get the foundation for the described in "Software Architecture for Developers" described Software Guidebook 
  • Functional Overview ➡️ 2. Functional Overview
  • Quality Goals ➡️ 3. Quality Attributes
  • Business Context ➡️ 1. Context, 7. External Interface
  • Organisational Constraints ➡️ 4. Constraints
  • Technical Constraints ➡️ 4. Constraints
  • Architectural Hypothesis ➡️ 13. Decision Log

Download

On the following page you can download the Software Architecture Canvas in high resolution.

Software Architecture Canvas Download
On this page you can download the canvas as PDF or PNG in high resolution.

Examples

Software Architecture Canvas real-world Example #1: Tech Radar
In this article you can see an example of how the Software Architecturae Canvas can be used. The example is the Tech Radar as SaaS software.

Podcast (german)

Episode 96: Architecture Canvas (1): Die Starthilfe
In dieser Podcastfolge sprechen Gernot Starke und Patrick Roos über eine pragmatische Starthilfe für Architekturprojekte: den Architecture Inception Canvas.

Podcast about the Architecture Inception Canvas (former Software Architecture Canvas) in German with Gernot Starke and Patrick Roos

Contact

If you have any questions or feedback about the Software Architecture Canvas, please contact me.

Contact
Hi! 👋 You can contact me through multiple channels. * Book a get-to-know on Calendly * Follow me on Twitter * Connect on LinkedIn * Inform about our services on the Company Website * Write an E-Mail My address: Fellow GmbH Ebenaustrasse 24 6048 Horw