How I work an architecture kata

Why I work katas

A kata is a practice exercise. I keep it apart from my production projects, and every brief is fictional. No kata describes the internal systems of a real company.

Each brief sets a hard problem in one sector: instant payments, health data exchange, telecom, insurance, retail pricing. It gives a background, eight requirements and a list of deliverables. Most of these sectors are far from my daily work. A few sit close to it, such as a warehouse migration or a price intelligence platform.

The goal is not a perfect design. It is to rehearse one habit. Every component should follow from a constraint, not from a favourite tool.

The steps

1. The brief. Eight requirements, R1 to R8, and every number in them: volumes, latency targets, retention periods, budgets. Those numbers drive the capacity arithmetic later.
2. The constraint and the open questions. I name the one constraint that shapes the design, in one sentence. Then I write eight numbered assumptions, A1 to A8, each with a figure I would want a real team to confirm. Whatever I cannot settle goes on a list of open questions.
3. A 30-minute live drawing. One page with 12 to 18 boxes. Security and observability run as two bars along the bottom. If the story does not fit in one glance, the design is not clear yet.
4. A four-page set. Page one is the solution overview. Page two follows the data hop by hop and explains each guarantee. Page three covers deployment, security and monitoring, with regulations cited by article where they apply. Page four holds a six-step contract for adding the next source or team. It also projects every component onto AWS, Azure and Google Cloud.
5. Component rationale and a licence table. One table pairs each need with a choice and says why the alternatives lost. Every row starts from the need, not from the product. A second table lists each licence and the company that sells support. I also name one component chosen differently for this kata, and why. That keeps the katas from turning into one template.
6. Capacity arithmetic. Six to eight rows, each with the calculation written out. In the GenAI agents kata, 8,000 employees, 25% of them active, three questions each, give about 6,000 questions a day. That figure then sizes the token budget, the GPU pool and two years of evidence storage.
7. Requirement mapping. Each requirement points to the part of the design that answers it, with the figure number. A requirement with no place in the design is a gap, not a detail.
8. Open points. Five or six open points close the kata, and the first three also sit on the overview page. A set of hard questions with short answers follows. They test whether the diagrams and the text still agree.

What I do not measure

The numbers in a kata are design estimates. Nothing is load-tested, and no system runs. That is why each kata ends with outcome notes marked as design assumptions, not measurements.

A claim also never goes further than its mechanism. I do not write “exactly once” or “no data loss” on its own. If the mechanism is asynchronous replication, the text says the recovery point equals the replication lag. It also says what happens inside that window.

Open source and licence choices

I prefer Apache 2.0 and MIT, then other OSI-approved licences such as BSD, MPL or the PostgreSQL licence. Each component also needs a company behind it that sells support.

Source-available licences are ruled out, and the tables say so. Redpanda and HashiCorp Vault fell out over the Business Source License, so OpenBao takes the place of Vault. Valkey replaces Redis after the Redis 7.x licence change. OpenSearch replaces Elasticsearch, and Flowable or Temporal replace Camunda 8. Ceph replaces MinIO, whose community edition narrowed. TimescaleDB went out because its compression sits under the Timescale License.

Some exceptions are unavoidable, and I name them. Commercial LLM provider APIs are one, when a brief asks for them. A managed service such as Cloud Composer is another, when it is already part of the platform.

The cloud projection follows the same rule. When a managed service is not a true equivalent, its cell carries a short gap tag, such as “Beam rewrite” or “no transactions”.

How to read a kata

Start with the cover image, the 30-minute live drawing, which tells the whole story in one view. Then read the component table, because most of the reasoning sits in its “why” column. The decisions and trade-offs come next, each with its cost. “What I would revisit” lists the questions I would ask a real team first.

Diagram labels are in English. Behind each kata sits a longer written solution, a Turkish PDF of 14 to 18 pages.

Where AI tools come in

I used AI tools to draft the written solutions and the diagram specifications. Each diagram is a small spec in Python code. One build renders the draw.io file and the PNG images from it, so the picture never drifts from the diagram. The component choices, the trade-offs and the open questions are my decisions.

The katas: all architecture katas.