How to Make an Engineering Architecture Explainer for Your Team
The best architecture explainer is not a tour of every box on the diagram. It traces one real request through the system, then shows what happens when a piece fails. How to script one for new engineers, with a full worked example of an order going through six services.
By openCanviz • October 17, 2026
7 min read
To make an architecture explainer for your team, trace one real request through the system from the user's click to the last side effect, and draw each service as the request reaches it. Do not tour the architecture diagram box by box. Pick the request that touches the most important services (placing an order, uploading a file, running a job), write about 750 words of narration for a five minute video, then add one scene for each place the request can fail and what happens when it does. Use the real service names, mark which calls are synchronous and which go through a queue, and put a date and an owner on the last scene, because architecture changes and the video will not change itself.
Why the box tour does not work
Most architecture explainers, live or recorded, start from the big diagram and walk round it. "This is the API gateway. This is the orders service. This is Kafka." By the eighth box the new engineer has a list of names and no idea how they relate.
The names only mean something once you know what flows between them. A request path gives the viewer a thread to hold. Each new service appears at the moment something needs it, so the viewer learns what it is for at the same time as its name.
| Approach | What the new engineer remembers a week later |
| Box tour of the full diagram | Some names, roughly where they sit on the slide |
| One request traced end to end | What each service does, and the order things happen in |
| Request path plus failure scenes | The above, plus where to look when it breaks at 3am |
The third row is the one worth making. It is also the one a live walkthrough rarely gets to, because the hour runs out first.
Choose the request
The right request touches most of the services a new engineer will work on, and crosses at least one asynchronous boundary. For an e-commerce system that is placing an order. For a file platform it is an upload that gets processed. For a data team it is a scheduled job from trigger to dashboard.
If no single request covers enough, make two short videos rather than one long one. Five minutes per path is about the limit before people start skimming.
Worked example: how an order moves through our services
Here is the script outline for a five minute explainer of a typical service setup. Swap in your own names.
| Scene | What is drawn | Narration (key line) |
| 1 | A phone, a Place order button, and an arrow into a box labelled api-gateway | "When a customer taps Place order, the app sends one HTTPS request to api-gateway. Everything else happens behind it." |
| 2 | api-gateway checking a token against auth | "The gateway asks auth whether the token is valid. That is a synchronous call with a 200 millisecond timeout, and if auth is down, nobody can order." |
| 3 | orders service writing a row to its own Postgres, status PENDING | "The gateway forwards the request to orders, which writes the order to its own database with status pending. No other service reads that database." |
| 4 | orders calling payments, which calls the card processor | "Orders calls payments synchronously, because we will not confirm an order we have not charged. Payments talks to the card processor and returns approved or declined." |
| 5 | orders publishing OrderPlaced onto a Kafka topic | "Once payment is approved, orders sets the status to confirmed and publishes an OrderPlaced event. The customer gets their confirmation now. Everything after this is asynchronous." |
| 6 | Three consumers lifting the event off the topic: inventory, notifications, analytics | "Three services consume that event independently. Inventory reserves the stock, notifications sends the email, analytics records the sale. None of them can slow down the customer's request." |
| 7 | The full path drawn as one line, solid for synchronous, dashed for asynchronous | "So the rule is: solid lines must be fast and up, dashed lines can be slow or briefly down." |
| 8 | payments with a red cross, orders returning an error, nothing published | "If payments is down, the order stays pending, the customer sees an error, and nothing is published. No stock is reserved for an unpaid order." |
| 9 | notifications with a red cross, events piling up on the topic | "If notifications is down, orders still succeed. Events wait on the topic, and when notifications recovers it works through the backlog. Customers get their emails late, not never." |
| 10 | The owner, a date, and links: runbook, service catalogue, this doc | "This describes the system as of October. Owner: platform team. Runbooks are linked below." |
Scene 7 is the one people quote back to you. One drawing that separates the synchronous path from the asynchronous path explains more about how a system behaves under load than any amount of detail about individual services.
Scenes 8 and 9 are what make this an engineering explainer rather than an onboarding slide. They tell a new engineer what is critical, what is tolerant, and which dashboards to open when something is wrong.
What to leave out
Every service. A real system has forty. The request path touches seven. Name the rest in the doc that goes alongside, or make a second video for the second path.
Infrastructure detail. Kubernetes namespaces, load balancer types and instance sizes change too often and matter too little to the story. One scene saying "everything runs on our Kubernetes cluster in two regions" is enough.
Internal hostnames, credentials and customer data. They have no place in a video, and some companies do not allow them to be pasted into third-party tools at all. Check your company's policy before you paste an internal document anywhere. The explainer loses nothing by using service names only.
History. Why the monolith was split in 2021 is interesting, and belongs in a separate design doc or a one-line aside.
Make it
- 1
Pick one request
The one that touches the most services a new engineer will work on and crosses at least one queue or event bus.
- 2
Write the path as numbered steps
Who calls whom, synchronous or asynchronous, what gets written where. Check it against tracing data if you have it, not memory.
- 3
Add the failure scenes
For the two or three most important services on the path, one scene each: what the customer sees and what happens to the data when it is down.
- 4
Turn the steps into narration
About 750 words for five minutes, one paragraph per scene. Use the exact service names from your repos.
- 5
Paste it in and check the diagram
In openCanviz, paste the script with Keep my wording and choose whiteboard so each service draws as the request reaches it. Then check every arrow direction and every label against the real system, and fix them in the editor.
- 6
Date it and give it an owner
Put the month and the owning team on the last scene, and link the video from the service catalogue or onboarding doc.
Keeping it current
Architecture explainers rot. The fix is not to avoid making them, it is to make them cheap to update.
Keep the script in the repo. A markdown file next to the architecture docs, reviewed like any other change. When the system changes, the script changes in the same pull request.
Update scenes, not videos. When notifications moves from Kafka to a managed queue, only scenes 6 and 9 change. Edit those scenes, re-export, and leave the rest.
Review it every quarter. Watch it once with the on-call engineer. Anything that makes them wince gets fixed.
A video for a specific change, rather than the whole system, is a different job: see how to make a video to explain a pull request or design doc. For the version aimed at people who call your services from outside, how to make a video that explains how your API works. And if this is one video in a new hire's first week, how to make an employee onboarding video covers the rest of that series.
Common questions
How long should an architecture explainer be? Four to six minutes per request path. If you need more, you need another path, not a longer video.
Should a senior engineer narrate it? It helps if they are willing, because their voice carries authority and new engineers will meet them. Record the narration yourself and replace the generated voice if you want that. If not, a generated voice reading a script they wrote is fine.
Is this a replacement for the architecture doc? No. The doc is the reference, searchable and complete. The video is the first pass that makes the doc readable. Link each from the other.
What about systems with no clear request, like batch pipelines? Trace one record instead. A row arriving in the source system, landing in the warehouse, getting transformed, and appearing on a dashboard is the same shape as a request path.
Can I show a sequence diagram? Yes, and the request path above is really a sequence diagram drawn one step at a time. Building it as the narration describes each call is easier to follow than showing the finished diagram all at once.
Write scene 7 first
Draw your main request path once, solid lines for synchronous calls and dashed for asynchronous. If you cannot draw it from memory, that is the explainer your team needs most. It is free to start.
Turn any concept into an animated explainer
Type an outline, get a narrated, animated whiteboard video in minutes. No design skills, no timeline scrubbing. Free to start.
Keep reading
A public research video is not a shorter paper. It leads with why anyone should care, states one finding in everyday words, says plainly what it does not mean, and runs two to three minutes. A method, a jargon table, a worked script on sound and plant growth, and the checks to make before posting.
PowerPoint, Keynote, Excalidraw with excalidraw-animate, Figma, After Effects, Manim, Mermaid and openCanviz all animate diagrams, but they are good at different jobs. A fair comparison by what you start from, what you get out, and how long a two-minute diagram takes.
A diagram that builds should appear in the order you explain it, not the order it was drawn or laid out. Here are the build orders for flowcharts, architectures, sequences and loops, a worked password-reset flowchart, and how to do it in slides, code or a narrated tool.
Screen recordings are right for showing a tool. For explaining a concept such as OAuth, a drawn, narrated tutorial is faster to make, easier to follow and does not go stale when the UI changes. How to script one, with a scene by scene OAuth example.