Software architecture KATA

JArchitects’s held another awesome Tech Day on June, this edition focusing on Software System Architecture. Our guest speaker this time was Bart Blommaerts from BB Consulting.

The workshop started with a theoretical description of the theme followed by a few hands-on sessions (Architecture Kata).

After the theoretical introduction the attendees were challenged to put theory into practice. We were divided in small groups to discuss the design a solution for a given problem. Between every Kata session the teams had to explain the rationale behind their solution, so we could learn from each other’s ideas. In the spirit of JArchitects’ Tech days, another great knowledge sharing encounter.

What is a Kata?

The short answer is “practice opportunity”.

Kata is a Japanese word most commonly known on martial arts realm. The term translates to the English word ‘form’ and refers to choreographed patterns of movements practiced either solo or in pairs.

According to Bart Blommaerts “You might know the saying practice makes perfect, and Architectural Katas are exactly that: practicing. These Katas were born out of a simple desire — Software architects need a chance to practice being software architects.

Ted Neward also made quite important observation: “So how are we supposed to get great architects, if they only get the chance to architect fewer than a half-dozen times in their career?

In summary, this workshop was in fact a 6 hours practice where the JArchitects’ team had the opportunity share experiences and learn from each other while creating the software architecture of a given problem in a very positive atmosphere with a super dynamic approach.

Why System Architecture?

For every computational system, there are various stakeholder, customers, users, developers, to mention just a few. These stakeholders need to have a clear view on what needs to be built.

Reminder: every system has an architecture, even those where the architecture was not formalized. It could be good or bad architecture, but the fact is that the architecture exists anyway.

Therefore, we need a way to document decisions, models, designs and at the same time use some kind of notation/language to represent these elements in a way that all stakeholders can easily understand.

Thus, isn’t it better to ‘formally define’ the system architecture? How about an Architectural Description using views and perspectives?

If you are interested in going deeper, I strongly suggest to dive into the book “Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives”, by Nick Rozanski and Eóin Woods. And maybe even have it always close to, just in case.

Grady Booch once said “one cannot see the ocean’s currents by studying drops of water”. We can apply this quote into our context by saying you should always make some kind of architecture visualization. It’s a fine line between over and under documenting your software solution, however. Therefore, be aware of the fact and don’t over-document your system. Also remember the change is the only constant in software industry. Got the irony?

Goals of visualizing your architecture:

  • Consistency — Every stakeholder should have a clear understanding of all elements involved
  • Reporting — Architecture needs to be in the heads of the stakeholders
  • Checking and validating — Share the architecture with your different stakeholders
  • Share information — Other people might have experience with certain challenges

When creating visualization models, for any problem you have at hand, it is paramount you define properly the notation for the components you intend to include in the diagrams. This notation could be UML, some variation of UML, or even simple boxes, circles, lines and arrows, as long as they are consistent and clear in every diagram you create. You can start with more pragmatic approach with boxes and lines, and in case of necessity for your project, you can then change to a more formal notation.

“Don’t make things more complex than they need to be, boxes and lines are fine. Just make sure to be consistent and always provide a legend” Bart Blommaerts

One other detail to keep in mind: only document what’s useful.

The JArchitects’ Kata

The goal of this Kata workshop was to guide attendees in creating software architectures that meet the challenges of today’s complex and ever-evolving systems.

In this Kata we had a change to define/discuss the Architecture of ‘AM.I.SCK ‘, a medical assistant application which should support chat nurses answering questions from customers about potential health problems.

Some AM.I.SCK context:

  • Nurses that answer questions from patients via a chat platform
  • 250+ nurses worldwide, hundreds to thousands of customers
  • Access to medical histories
  • Assist nurses in providing medical diagnosis
  • Reach local medical staff, even ahead of time
  • Enable parts of the system for direct patient usage
  • Conversations are not considered medical records


  • Access patient medical histories
  • Provide an service-level agreement on turnaround time for interaction
  • Assist nurses in providing medical diagnosis
  • Support nurses geographically divergent from clients
  • Enable client customers to reach local medical staff (if necessary), contacting the local medical staff directly ahead of time (if necessary)
  • Eventually enable parts of the system for direct client customer use

During the hands-on moments the attendees had to define the 7 viewpoints (diagrams) that represent the System Architecture for “AM.I.SCK”. The viewpoints were:

  • Context view
  • Functional view
  • Information view
  • Concurrency view
  • Development view
  • Deployment view
  • Operational view

It was indeed a quite interesting workshop. Hands-on approach is always engaging!

Key takeaways

  1. Every system has an architecture, even those where the architecture was not formalized.
  2. Only document what’s useful
  3. Be explicit with definitions, notation, specifications and steps
  4. Respect your definitions
  5. Do not reinvent the wheel. There are companies out there that live only to solve some cross-cutting concern problems. If you have the opportunity, use their solution (service) and avoid at all costs to build your own.

References and resources

  • Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives website
  • The C4 model for software architecture