Architectural Katas

Which Tools Do You Need?

Architectural Katas

You need three things to run a kata, and architecturalkatas.com has all of them. Each one answers a different question you’ll have before you start.

Read the rules first if the format is new to you. Then take a random kata from the collection and use the facilitation guide to run it with your own team.

Architectural Decision Records

An architectural decision record, or ADR, is a short document that captures and explains a decision. It holds the context, the alternatives, and the consequences. A later reader can then see why a system looks the way it does.

In a kata, the records are the only memory your design has, and you write them as you design. Write one for each choice, such as where the data lives or how two parts communicate. Note the alternative you rejected and the cost you accept.

When a requirement changes, reread your records and write a new one to replace any whose context no longer holds.

In the workshop we use a simplified ADR template that fits on one A4 page. It holds up to three decisions, and each one follows the same pattern. You name the decision, write down two alternatives, and finish with the key trade-off between them.

ADR template

Release Timeline

A release timeline shows what ships when, with a date attached to each step. A date limits what can be built before it. The timeline forces the team to decide which needs come first and which can wait.

In a kata, a common practice is to split the delivery into phases such as MVP and Phase 1. Each phase gets a due date, such as Week 1, Month 1, or Q1. You scope the first release while you understand and prioritize, and you lay out the rest once you design.

Start with the earliest date and ask what the system must do by then. Everything else moves to a later phase, and each move changes other decisions:

A later phase can still shape the first one, so sketch what comes after the MVP before you settle how to build it. Whenever you move a requirement to a different phase, revisit these decisions.

In the workshop we use a simple timeline template on one landscape A4 page. It gives the MVP and each of three later phases a column of its own. Every column starts with a due date and leaves room below for what that phase covers.

Timeline template

C4 Diagrams

The C4 model is Simon Brown’s approach to diagramming software architecture. It describes a system at four levels of detail, from context down to code. Each level answers a different question for a different reader. Most teams only need the first two levels, and a kata is no different.

  • A system context diagram shows the system among its users and neighboring systems. Draw it first.

  • A container diagram shows the applications and data stores inside the system. Test your design against it.

  • A component diagram shows the parts inside one container. Draw one only if it adds value.

  • A code diagram shows the classes inside one component. It is out of scope for a kata.

Label every connection on each diagram, and keep the diagrams beside your ADRs. A diagram shows what you decided, and the record explains why.

We have a C4 cheat sheet in our FOSSCOMM 2026 booklet. It covers the four levels, a common notation, and tips for drawing your diagrams. The booklet also walks through an example for a learning management system.

C4 cheat sheet

Catas to Avoid

Catas to Avoid is a tongue-in-cheek collection of anti-patterns for architectural katas.

Some catas belong to the team at the table, and they show how you architect yourself into a corner:

Others belong to whoever runs the kata. The Over-Corrector jumps in at the first sign of trouble. The Tech-Savvy Stakeholder plays the business role but hands teams the solution.

It’s worth a read before your next kata, and again after it.

Using the Tools in a Kata

Each of these tools has its place in a kata, from the first release you scope to the records you defend in front of the room.

Put the tools to work