Software architecture is more than just technology and implementation. It also involves coordination, decision-making, knowledge creation and sharing - and above all, teamwork. As is often the case in complex systems, the knowledge exists - but unfortunately, not always where it’s needed. So where does it live? In team members’ heads, in various tools, or old-school on notes, meeting minutes, or whiteboards.
At pentacor, we work across multiple teams on different client projects. Along the way, we constantly make technical decisions that shape and influence our systems’ architecture. Initially, each team makes these decisions independently, within its own context. From an architectural perspective, by the end of last year we were asking ourselves: How can we make these decisions visible across teams? How can we create a structured, yet practical overview of how we live architecture day to day? And how can the entire company benefit from it?
The answer: we use a canvas. Since there wasn’t an existing one we could use out of the box, we decided to create our own.
Isn’t This Already a Thing?
The idea for a canvas came up because we were already using canvases for various topics in our projects. At first, we explored existing formats like the Architecture Inception Canvas (AIC), the Architecture Communication Canvas (ACC), and elements of the arc42 model. All of them offer valuable perspectives - on business goals, functional requirements, system environments, or risks.
But something was missing.
We needed a format that focuses less on what and with what, and more on how and why. A format that doesn’t just document what we built, but also shows how we got there and what we learned along the way. One that actively incorporates the team’s experiential knowledge as well.
The p-Architecture Knowledge Canvas
What emerged is a deliberately simple canvas that can serve as a foundation for deeper discussions. It can be filled out in a roughly two-hour workshop together with developers, product owners, the agile coach, and - if available - solution architects. We include not only the developers but also those who contribute domain knowledge or influence agile processes, because valuable experience also resides within these roles and teams.
The canvas also thrives on iteration. Decisions made at an earlier stage may later prove to be excellent - or sometimes less than ideal.
Similar to the AIC and ACC, the canvas is structured into three main areas, each with its corresponding fields.
Prerequisites
Every project has a purpose, along with preconditions and rules that must be followed. The “Quality Goals” aspect is often overlooked - or not formally documented - and in our experience, it regularly sparks discussions. This is where active investment and conversation are crucial, because all key decisions should ultimately be driven by quality.
- Business Case & Goals: What is the purpose of the software? Which requirements drive us?
- Quality Goals: Which qualities are most important? What takes precedence - security, performance, scalability?
- Constraints: What limits are we working within? Time, budget, tools, or regulatory requirements?
Solution & Communication
How we communicate and share knowledge - enabling everyone on the team to participate in and make decisions - is just as important as the solution itself. This is why these topics form the core of the canvas.
- Knowledge Sharing Approaches: How do we distribute knowledge within the team? In addition to technical expertise, domain knowledge is especially important here.
- Architectural Approach / Solution Strategy: Which solution ideas, principles, and patterns guide us? What is our architectural core? What have we implemented so far?
- Technologies: Which technologies are we using? In which areas are we experts, and where are we experimenting?
Reason & Learnings
The final section captures accumulated experiences, reflecting both on decisions made and the knowledge gained.
- Decisions (Good & Bad): What worked? What didn’t? What would we do the same way again—or avoid next time? The answers are intentionally separated into methods, architecture, and technologies.
- Learnings & Insights: What did we take away? What can we do better in future projects from the start? What advice would we give to other teams?
Some fields are similar to those in the AIC or ACC, or are inspired by arc42. Others deliberately introduce new perspectives. What matters most to us is not comprehensive documentation, but rather guidance, reflection, and dialogue.
And What’s the Benefit?
The canvas helps an individual team actively engage with its architecture. It makes transparent how we have thought about and implemented the architecture. Decisions - good or bad - are made explicit. It helps identify gaps, create clarity, and improve communication.
Most importantly, it provides a foundation for making future decisions more consciously and with better information. It also allows us to explain our architecture in a way that others can understand - both internally and externally, technically and organizationally.
Across teams, the canvas provides a quick and easy overview of what other teams are working on. You can see who is using which technologies and which decisions others view positively. This helps identify whom to consult for specific questions about technology or communication approaches. It also makes visible how certain quality requirements led to particular solutions.
Things We’ve Learned
By now, we’ve used the canvas in multiple projects with teams ranging from three to eight people across different client settings. What became clear: discussions about qualities, knowledge sharing, and architectural approaches were always extremely valuable. Some even said that the discussions themselves were more valuable than the completed fields.
- A good architecture canvas asks the right questions and enables open discussion. Filling it out isn’t about completeness - it’s about relevance. Discuss everything openly. Especially in teams with frequent personnel changes, the “old hands” often know a lot that isn’t formally documented but is crucial for newer team members.
- Not everything needs to go into the canvas. What matters most is that the conversations happen. The canvas is a catalyst, not an archive. It should serve as a brief documentation that provides an entry point for deeper exploration.
- Architecture is also a social system. Focusing only on components, technologies, and technical aspects misses the real levers for good software architecture.
Want to give it a try?
The canvas is intentionally open-ended. If you’d like to use it in your project, go ahead! We welcome feedback, shared experiences, and any adaptations you make.
It can help you gain clarity, spot patterns, and kick-start - or enhance - the conversation around architecture.
One thing is clear: good architecture doesn’t happen by accident. It comes from active engagement, open discussion, and, of course, documentation - concise but meaningful - so that your work can be easily referenced and built upon in the future.
Download: p-Architecture Knowledge Canvas
