How to turn an architecture decision record into an explainer video
Kario Team · November 1, 2026 · 3 min read
Kario turns an architecture decision record into a short explainer with diagrams. Attach the ADR in the chat (.md, .txt or .pdf) or paste its text, and say who the video is for. Kario draws the systems it names as boxes and arrows, then animates what each section says: the problem in the context, the new design in the decision, and the trade-offs in the consequences. Every box, label and number is a layer you can edit.
The video above is 33 seconds long. It was made from one ADR, ADR-0042 at Fernbill, an invoicing app we made up for these examples.
The ADR
An ADR records one design decision and why it was made (adr.github.io). Michael Nygard, who proposed the format, gives each one a title, a status, a context, a decision and its consequences, and keeps it to one or two pages, because "nobody ever reads large documents" (Documenting Architecture Decisions). This is the one the video was made from:
# ADR-0042: Render invoice PDFs on a queue
Status: Accepted, 28 October 2026
## Context
Invoice PDFs are rendered inside the API request.
At month-end, p95 reaches 9 s and requests time out.
## Decision
The API puts a job on a queue and returns at once.
PDF workers render the file, store it and email the client a link.
## Consequences
Invoices show "Preparing PDF" for a few seconds.
Failed renders retry, up to three times.
One more service to run and watch.
What happens in it
- The ADR opens on its own, then moves aside to make room. A band moves down it, so the viewer always knows which section the diagram is showing.
- Context. The web app, the API and Postgres appear. Requests pile up under the API, which is still rendering PDFs, while p95 climbs from 0.4 to 9 seconds. Then a request times out with a 504.
- Decision. The "renders PDFs" step leaves the API and docks in a new PDF workers box. A queue, storage and email join it, and jobs flow round the loop. The API now answers "202 Accepted" in 140 ms.
- Consequences. An invoice shows "Preparing PDF…" until the file is ready. One render fails, and the retry goes through. A tag on the workers reads "+1 service to run and watch".
- The end card states the decision: "Invoice PDFs now render on a queue."
There's no voiceover. The ADR's own words and the diagram carry it, so it works with the sound off.
Make one from your ADR
- Attach the ADR as a .md, .txt or .pdf file, or paste the text. One decision per video.
- Say who will watch it. Engineers joining the team need the systems named. Product or support need to know what users will see.
- Name the systems the diagram should show, if the ADR doesn't. A box needs a name: "API", "Queue", "PDF workers".
- Give the numbers that make the case, such as a p95, an error rate or a cost. The video shows the numbers you give it.
- Say where it will play: a pull request, an all-hands, a design review, a post. 16:9 is the default. A vertical or square version comes as another board in the same project.
Ask for a voiceover if you want one narrated. Pick from Kario's voices or attach your own recording, and the diagram is timed to each word.
When the decision changes
Nygard's rule is to keep a reversed decision and mark it superseded, with a reference to the one that replaces it. The video can follow the same rule. Open the project, add the new ADR, and ask Kario to make a board for it. It keeps the layout, colours and boxes and redraws what changed. A renamed service or a corrected number is just a retype.
For a narrated explainer of a whole topic rather than one decision, see how to make a narrated explainer video with AI.