From understanding a client’s business requirements to describing it to your team, understanding why you are doing what you are doing helps to create architecture everyone can understand. But even if you do follow all the rules, how can you be sure you are designing good architecture?
That was the question we wanted to answer. As architects, we need to know the solution we propose is the best it can be for clients. That what we are doing is the right choice, the right direction, and the right solution. That’s why we took part in the O’Reilly Winter Architectural Kata. We wanted to test ourselves and see how we could improve our work.
Why take part in katas?
Let’s start with some background, a while back at Global Software Architecture Summit GSAS, Wojciech Kasa & Sebastian Dąbkowski (two other team members) approached Mark Richards for advice. We were planning on running our own in-house kata, and training sessions.
Mark took the time to explain that it’s hard to compare architecture. That, the most important part is the presentation. Not just the tools used, but how developers will convince you they are the best for the job.
But more so, he convinced them it was a good idea to get their own experience. To test what they knew and learn from the best architects in the world. And to use what they had learned to spread this knowledge.
That’s what pushed us to join the kata. We joined the competition under the name Bluzbrothers. The team was made up of four people; Sebastian Dąbkowski, Piotr Filipowicz, Artur Kruszewski & Wojciech Kasa. And we were excited to test how much we knew about architecture, and what we could learn.
What are Katas and why are they important?
A software architecture kata is a training exercise designed to help developers and architects practice and refine their skills in designing software systems. It involves tackling hypothetical design problems where participants can experiment with architectural concepts and techniques. This practice helps improve problem-solving skills, understand various architectural patterns, and enhance communication within a team setting.
How we approached the architecture
One common mistake in architecture is going too deep into each element without considering the broader picture. This leads to complex solutions that fail to tell the overall story. Stakeholders often can’t see the “forest through the trees”. They focus on just the technical details, but it lacks relevance to users and others who don’t care about the finer details. Think how a CEO from a business background would view the architecture.
Typically, diagrams and documents demonstrate how systems function, but they don’t explain why certain decisions were made. When non-technical people review these materials, they ask “Why?”
The requirements of a project detail the “how,” but the supplementary documentation—such as ADRs—explains “why” specific paths were chosen, providing a reference point.
Like in building architecture, where the structure reflects its internal purpose and adds emotional context for the client, software architecture needs to do the same. This is a form of architectural storytelling, and it formed the basis of our approach.
What is architecture storytelling?
Architectural storytelling effectively communicates design to everyone, from business leaders to developers. It blends functional requirements, architectural decisions, and actionable steps into a clear narrative. This approach helps all stakeholders—team leaders, architects, developers—see the value and relevance in the design, promoting better understanding and collaboration across the project.
Our winning approach
At every stage, we needed to describe why an action took place not just the how. To help separate our approach, we divided it into 6 parts. This created, what we called, the Architectural Rubik’s Cube.
I won’t go into a lot of detail here, and just give you a general breakdown of the six sides of our Rubix’s Cube.
Functional requirements perspective
On the first side of the Architectural Rubik’s Cube, we focused on the Functional Requirements Perspective. Here, we gather and document the essential functions the application must perform. This aligns the product with user needs and business goals. Techniques like event storming and actor-action mapping are employed to visualize system processes and ensure user interactions are effectively designed.
Non-Functional requirements perspective
On the other side, we delve into the Non-Functional Requirements Perspective. This involves identifying both implicit and explicit requirements that address system performance issues like elasticity and evolvability, ensuring the architecture can support long-term robustness and adaptability.
Constraints
Turning the cube, we encounter the Constraints. This aspect involves understanding and documenting the technological, legal, and budgetary limits that define the project’s boundaries. This influences the architectural and development approach.
Technical architecture perspective
From the Technical Architecture Perspective, we selected an architectural style that uses real-time data processing and diagrams to explain how the application interacts with other systems. This is complemented by designing an auto-scalable infrastructure and implementing fitness functions to maintain system integrity under varying conditions.
Fitness functions
Another rotation brings us to the fitness functions, where system testing and performance validation ensure the architecture fulfills all functional and non-functional requirements within the intended environment.
Team Building and Role Division Perspective
Finally, the Team Building and Role Division Perspective emphasizes using context mapping to define the team topologies and boundaries. This helped with communication and collaboration within the project team. It made it easier for everyone to work productively
There’s a lot more to it than this, and you can explore our full architectural model here in a dedicated case study.
What lessons did the Katas teach us?
Here’s what we learned while working as a team:
- Building team dynamics
We realized early on that knowing each other wasn’t the same as working together. Thrown into the mix, we experienced all the classic stages of norming and storming. It wasn’t smooth, especially when we had to quickly align our approaches and distill the best solutions amidst short bursts of discussion. This phase taught us the invaluable lesson of adapting and melding varied ideas into a cohesive plan under pressure. - Embracing wide angles in group calls
Every group meeting was a chance to present and refine our solution. Here, the key takeaway was to think broadly rather than deeply. Viewing our plans from multiple perspectives allowed us to be comprehensive and inclusive in our approach, ensuring no stone was left unturned. - Valuing jury feedback
Feedback from the jury highlighted the strengths of our proposal—particularly our flexible approach that left space for developers to choose suitable technologies. This balance was crucial; too restrictive and we’d blow the budget, too loose and the architecture could fail. Our presentation’s narrative was also well-received, underscoring the impact of aligning the architectural choices directly with our goals. - Storytelling over specs
While technical specifics are crucial, our team chose to focus more on the narrative. We wrote a story that connected directly with the performance needs of the project. This approach not only made our presentation more relatable but also highlighted the practical implications of our architectural decisions. - Harmonizing visual communications
Our team initially struggled with inconsistency in our visual aids, as everyone used different tools, colors, and styles. The lesson was clear: unify to clarify. By standardizing our illustrations, we improved our ability to communicate ideas clearly and effectively. - The art of collaboration
Real collaboration requires a balance between listening, observing, and communicating. We learned to listen first, use our eyes to confirm details, and then communicate effectively. This method proved essential in aligning our diverse thoughts and approaches. - Scheduling and syncing together
One of the biggest challenges was coordinating our schedules. The initial days post-kickoff were silent, leading to a crunch where time was tight, and not everyone could sync. We realized the importance of planning for asynchronous work and accommodating different work rhythms. - Independent Yet Interconnected
Despite our efforts to work together, there were phases of independent work—or storming. This was both a challenge and a plus, as it allowed individual reflections and contributions, which we then integrated into the solution.
Want to develop your own Kata experience?
We occasionally run our own katas open to developers looking to improve their skills & learn something new. To stay informed when the next event is happening click here.
Advice to anyone thinking about taking part in Katas
Are you thinking about tackling the Kata? Here are some friendly tips to get you started:
- Engage with the Jury
Don’t hesitate to ask the jury questions. Engaging with them can provide clarity and ensure that your solution aligns with the goals and expectations of the Kata. Their insights might guide you toward what is most valued in your submissions. - Identify the Core Problem
Focus on uncovering the core problem before diving into detailed solutions. Often, a broader issue needs addressing before the finer points of architecture come into play. Recognize the global significance and support mechanisms that are essential for addressing these core challenges effectively. Prioritize these foundational elements in your approach. - Adopt a Broad Perspective
Look widely rather than deeply at the outset. A broad overview allows you to see the problem from various angles, ensuring that your solution is well-rounded and considers all necessary aspects. This approach helps in forming a more effective and comprehensive response to the problem. - Master the Art of Storytelling
No matter how technically sound your architecture might be, if you cannot communicate its value effectively, it will not resonate. Learn to tell a compelling story about your project. This not only captivates your audience but also highlights the practical impact and relevance of your architectural choices. A well-told story can be the bridge between a good architecture and a winning proposal.
Conclusion
If you’re considering whether to participate in a kata, our experience suggests it’s well worth the effort. The insights and improvements you gain can significantly impact your approach to architectural design. Give it a try and see for yourself the difference it can make.
And for our team? Looking ahead, we’re excited to apply what we’ve learned to our in-house activities.
