Skip to main content

Architecture Communication Katas

Focused, repeatable drills for diagramming, turning stakeholder language into measurable qualities, critiquing existing artifacts, and writing a fitness function end-to-end. Run each kata multiple times until the moves are automatic.

Kata 1: C4 Context + Container Diagram​

Time limit: 30 minutes
Goal: Produce a readable C4 Context and Container diagram for a known system, with audience, scope, and legend.
Setup: Pick a well-known application you did not design (examples: a grocery delivery app, a social network, an online banking portal, a ride-sharing platform, a note-taking app like Notion, a video-conferencing service).

Deliverable:

  1. One C4 Context diagram: the system as a single box, surrounded by users (roles, not personas) and external systems. State audience and scope in the title.
  2. One C4 Container diagram: the same system decomposed into containers (deployable units) with technology, one-line purpose, and relationships (verb + protocol on every line).
  3. A short "out of scope" note: what this diagram deliberately does not show.

Repeat until: you can produce both diagrams for a new system, from scratch, in 30 minutes, with a legend and labeled relationships, and a reader unfamiliar with the system can correctly describe its shape after reading them.

Anti-goals:

  • no unlabeled arrows
  • no box called just "service" or "API"
  • no diagram without audience

Kata 2: User Story to Explicit Qualities​

Time limit: 15 minutes per story
Goal: Turn a user story into the measurable quality requirements it implies.
Setup: Pick 3 user stories from any product backlog. Or invent them:

  • As a support agent, I can see a customer's order history in under 2 seconds so I can answer without keeping them on hold.
  • As a homeowner, I can arm my security system from anywhere so I feel safe when I leave.
  • As a teller, I can reverse a mistyped transaction within 5 minutes so I can correct errors before end-of-day.

For each story, produce:

  1. The functional requirement in one sentence.
  2. At least three quality requirements implied, each in scenario form (stimulus, environment, response, response measure).
  3. Which top-3 characteristics this story pulls toward.
  4. One sentence naming what is implicit (e.g., "nobody said auditability, but this is banking").

Repeat until: for a new story in a domain you know, you can produce three scenarios in 15 minutes without looking up the template.

Anti-goals:

  • no adjective-only qualities ("fast," "secure")
  • no quality measure that cannot be verified by a test or monitor
  • no silent omissions of domain-implicit qualities

Kata 3: Critique a Boxes-and-Lines Diagram​

Time limit: 20 minutes
Goal: Take an ambiguous architecture diagram and rewrite it so a new engineer can interpret it unsupervised.
Setup: Start from this intentionally-bad diagram of an IoT platform.

+----------+     +-----------+     +-----------+
|  Client  |---->|    API    |---->|  Service  |
+----------+     +-----------+     +-----------+
                       |                |
                       v                v
                 +-----------+    +-----------+
                 |  Database |    |   Queue   |
                 +-----------+    +-----------+

Produce:

  1. A written critique: what is ambiguous, what is missing, what the reader cannot conclude from it. Name at least 6 issues.
  2. A rewrite as a C4 Container diagram (Mermaid or drawn) of the same system, with:
    • audience and scope stated in the title
    • every box: name + role + technology + one-line purpose
    • every line: verb + protocol
    • a legend if shapes or colors carry meaning
    • an explicit "out of scope" note
  3. One sentence stating the decision or question the rewritten diagram now supports.

Repeat until: you can execute the critique and rewrite in 20 minutes for a new bad diagram, and a reader unfamiliar with the system can describe what each box does.

Anti-goals:

  • rewriting with the same ambiguities in prettier shapes
  • adding detail not related to the audience
  • no legend on a diagram that needs one

Kata 4: Write a Fitness Function End-to-End​

Time limit: 45 minutes
Goal: Pick one architectural characteristic, write a runnable fitness function, and wire it into a pipeline.
Setup: Start from one of your top-3 characteristics for a real or realistic system. Not "testability in general" - one specific scenario, like "the teller module must not import ledger internals" or "p95 of GET /videos/{id}/manifest must be under 120 ms."

Deliverable:

  1. The scenario (one sentence, including measure).
  2. The failure signal (one sentence: "what would tell me this broke").
  3. A runnable check. Actual code, not pseudo-code. Acceptable forms:
    • a Python or Bash script
    • an import-linter contract / ArchUnit rule / dependency-cruiser config
    • a Spectral / OpenAPI lint rule
    • a k6 / Locust load-test script asserting a threshold
    • a log-scanning query with an assertion on count or pattern
  4. Pipeline wiring: the actual job, step, or cron that would run it, including failure behavior (block merge, alert, page).
  5. Ownership: who revisits this quarterly, and what stale-signal they are looking for.

Repeat until: you can produce all five parts for a new characteristic in 45 minutes, and the check runs in CI or a cron without manual work.

Anti-goals:

  • dashboards or "review this weekly" instead of automation
  • checks that pass trivially ("if the service responds at all")
  • unowned functions that nobody revisits

Completion Standard​

  • Can produce C4 Context + Container for a new system in 30 minutes
  • Can turn a user story into 3 measurable quality scenarios in 15 minutes
  • Can critique a boxes-and-lines diagram with at least 6 issues named and rewrite it cleanly in 20 minutes
  • Can write a runnable fitness function end-to-end in 45 minutes, including pipeline wiring
  • Can explain each kata's moves to a junior engineer without referring to notes