Your Architecture Has a Story. Show More Than the Boxes.
Overview
You've built something interesting. Now you need to explain it. So you open the architecture diagram, point at a few boxes, and start talking. Five minutes later, you're explaining the third arrow while half the room is still trying to understand the first one. Sound familiar?
I wanted a better way to do this. Not because architecture diagrams are bad (I quite like a good diagram), but because showing the end result doesn't necessarily help someone understand how it works, or why you built it that way. So I built Architecture Presenter , a GitHub Copilot CLI plugin that helps turn project evidence into an interactive, step-by-step architecture walkthrough.
I'm sharing it because I think it could be useful beyond my own projects. You can try it on yours, adapt the presentation to your audience, and contribute if you see something that could work better.
A walkthrough, not just another diagram
The idea is simple: start with the context, introduce the components, and add the connections when they become relevant. A build-up, rather than everything on screen at once. You can inspect a component for more context, switch between architecture and delivery stories, or present the walkthrough using a keyboard or presentation clicker.
Copilot prepares the content from your project, and the plugin provides the reusable presenter engine. Your project brings its own architecture and evidence, not the assumptions or example system from mine.
Here's what the output looks like. This short, silent preview shows the architecture building up in place, followed by a switch to decision commentary and dark appearance. It was captured from the plugin's actual HTML output, using a fictional delivery platform adapted from its test example.
Prefer to explore it yourself? Open the interactive demo . Use Next or the arrow keys to advance, Journeys to switch stories, and Design to change the appearance or layout.
The boxes are only part of the story
To me, this is the most interesting part. A diagram can tell you that an application talks to a database through a private endpoint. It doesn't necessarily tell you why that choice was made, what we tried before, or which problem forced us to revisit the design.
In some cases, understanding why and how something was built makes all the difference. It changes the conversation from "these are the services we used" to "this was the requirement, this was the trade-off, and this is what we learned."
That's why the grounding isn't limited to the current source code. When preparing a presenter, Copilot can use the repository history alongside the relevant local GitHub Copilot CLI sessions. The repository gives you the implementation and how it changed: commits, infrastructure, workflows, documentation, and recorded decisions. The local sessions can add the conversation around those changes: what we were trying to achieve, which approaches we considered, what failed, and how we arrived at the solution.
If you've read Part 2: The Long Conversation , you'll recognize why I find this valuable. Those longer sessions contain more than instructions and generated code. They often contain the reasoning that never made it into a README.
There's an important distinction here, though. A conversation is evidence of what we discussed, not proof that we implemented it. The session history needs to be checked against the repository and any available deployment evidence. If a local session isn't available, that context is missing. The right response is to make the gap explicit, not invent a convincing backstory.
You don't need architecture decision records (ADRs), formally defined principles, or local Copilot sessions to get started. Where documented rationale exists, use it. Where it doesn't, explain the architecture using the available source evidence. Decision and principle commentary is optional, and explanations distinguish documented rationale, observations, inferences, and suggestions.
This grounding happens while Copilot prepares the content. The finished presenter doesn't connect to your session history, and it shouldn't become an export of your conversations. You still review which explanations and source references belong in an audience-facing walkthrough.
Build understanding without moving the furniture
One design decision I feel quite strongly about: the diagram stays put. Components keep their positions as you move through the story, and responsibility boundaries are visible from the beginning. More of the architecture appears with each reveal, but the camera doesn't keep zooming out or rearranging everything.
It sounds like a small detail, but think about it from the audience's perspective. They're already learning what the components do. Making them rediscover where everything lives adds work without adding understanding. You can deliberately zoom in to inspect something, but the default is a stable overview.
The same applies to the explanation around each step. Rather than just highlighting another box, the presenter can explain the requirement, the decision, the value, and the trade-off when there is evidence to support them. Not every reveal needs commentary. Architecture-only journeys leave the commentary ribbon out, and mixed journeys keep the map stable as commentary appears or disappears.
One project, different conversations
Not everyone needs the same walkthrough. Sometimes I want to explain the system itself. Sometimes the interesting part is how we build and ship it. And sometimes I want to talk about the engineering lessons, including the things that didn't work the first time.
The plugin supports independent journeys for those conversations. You can select the architecture story, the delivery story, or an engineering-learning story without first sitting through another one. They're grounded in the same project, but they answer different questions.
For example, you can ask:
1Build independent architecture, delivery and engineering-learnings
2journeys for this project. Ground them in the repository history
3and relevant local GitHub Copilot CLI sessions. Include the
4decisions, trade-offs and evidence limits, not just the components.
Of course, not every project needs three journeys. And a recorded discussion about an approach doesn't automatically qualify as an engineering lesson. There needs to be something concrete to explain and evidence to support it. Otherwise, we're just adding more content, which is exactly what I was trying to avoid.
Something I can actually use on stage
The output is a standalone HTML presenter with progressive reveals, keyboard and clicker navigation, fullscreen, blackout, and contextual inspection. Stage layouts use viewport-scaled typography to help keep the explanation readable. Once generated, it works offline: no running web server, CDN, runtime MCP connection, or cloud credentials required to present it.
I like that separation. Copilot helps prepare the story, but I don't need a live AI connection to move to the next step during a session. And the project keeps the generation sources, alongside SVG and editable Excalidraw companions, so I can review, adjust, and regenerate the content later.
It also keeps the distinction between implemented, foundation, external, and target states explicit. An infrastructure template isn't proof of a running workload, and a planned component shouldn't quietly become part of the current architecture because it looks good in the diagram. A useful presenter needs to be honest about that.
Your project, your presentation
The plugin uses Microsoft Fluent by default, but the layout, visual theme, and light or dark appearance are separate choices. Explore, Stage, and Stage Ribbon provide different ways to use the same content, without tying your branding to a particular layout.
You can define your own JSON themes and preset-based layouts at project, repository, user, or machine scope without forking the engine. A team can keep its designs with the repository, while you can reuse your own designs across projects. User libraries can optionally live in OneDrive or another synced folder, with explicitly selected profiles rather than automatically mixing libraries.
The project keeps a snapshot of the selected design definitions, too. Someone else can rebuild the presenter without needing your personal theme library, and unselected designs from that library aren't copied along with it. The design system guide covers setup and customization.
Try it yourself
Install the plugin with:
1copilot plugin install timschps/architecture-presenter
You'll need Python 3.10 or later for generation. The repository documents the prerequisites for browser validation as well.
Start a new Copilot CLI session in your project and ask:
1Create an architecture presenter for this project using the
2fixed-overview standard. Use the repository history and relevant
3local GitHub Copilot CLI sessions, where available, to explain
4how and why it was built. Use documented decisions and principles
5where they exist, but don't invent missing rationale or require
6commentary for every reveal. Make missing evidence explicit.
Then review the result. Check whether the components, connections, decisions, and state labels match reality. Check what you're sharing with your audience. And if you're taking it on stage, rehearse with the actual clicker. Automated keyboard checks are useful, but they aren't your presentation rehearsal.
Try it, challenge it, contribute
I'd love to see how this works on projects other than mine. An onboarding walkthrough, an architecture review, or an explanation of how a service gets from commit to production: those are the kinds of conversations I have in mind.
Feedback and contributions are welcome. If you try it and something is confusing, breaks, or doesn't fit your architecture, open an issue . A concrete example of what you wanted to explain and where the presenter fell short would be especially useful. Please keep examples free of credentials, private conversations, and confidential project details.
Contributions don't have to be new features. Clearer documentation, examples, themes and layout presets, accessibility improvements, and fixes for presentation or navigation problems are all useful. If you have an improvement to share, pull requests are welcome . For a larger change, start with an issue so we can discuss the approach.
The goal isn't just a nicer diagram. It's helping someone understand a system, and sharing the reasoning where the evidence supports it. You can find the plugin, generation tools, and working standard on GitHub .
Enjoy!
Tim