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
- Motivation
- The Software Architecture Canvas Explained
- Compatibility with techniques for documenting software architecture
- Download
- Examples
- Contact
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)
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.
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?
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.
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.
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.
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.
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.
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.
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 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:
- Context
- Functional Overview
- Quality Attributes
- Constraints
- Principles
- Software Architecture
- External Interface
- Code
- Data
- Infrastructure Architecture
- Deployment
- Operation and Support
- Decision Log
You can find these recommended parts of the guide on the Software Architecture Canvas, which you can map directly.
- 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.
Examples
Podcast (german)
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.