Software Architecture

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

The Software Architecture Canvas is a collaborative technique for elaborating the software architecture playground of a software initiative. With this canvas, you can work efficiently, iteratively, and in a time-saving manner on the software architecture of your software products as a team sport.

The structure of the Software Architecture Canvas

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

Table of Contents

Motivation
The Software Architecture Canvas Explained
Compatibility with techniques for documenting software architecture
Download
Examples
Contact

🎉

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 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.

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.

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:

Functional Overview ➡️ 1. Introduction & Goals (1.1. Requirements Overview)
Quality Goals ➡️ 1. Introduction & Goals (1.2. Quality Goals)
Business Context ➡️ 3. Context & Scope (3.1 Business Context)
Organisational Constraints ➡️ 2. Constraints
Technical Contraints ➡️ 2. Constraints
Architectural hypothesis ➡️ 9. Architectural Decisions
Technical Challenges & Risks ➡️ 11. Risks and Technical Debt

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: