Diagrams that walk themselves: why I built DiaScope

When I’m working with a team on an AI system — a retrieval pipeline, a decision flow, a data ingestion architecture — there’s always a moment where we need to align on how it actually works.

Not just the developers. The clinical lead, the product owner, the regulatory person who needs to understand what the system decides and where. These are people with domain expertise who don’t read code, and shouldn’t need to.

The standard move is a diagram. And for years I’ve found diagrams to be genuinely the right medium for this — better than prose, better than code, better than a verbal explanation. A good diagram externalises the structure of a system in a way that a room full of people can reason about together.

The problem isn’t diagrams. The problem is everything around them.

The tools make it harder than it needs to be

The typical flow looks like this. You need to explain a system with eight components and three distinct flows. So you make a diagram. But eight components on one slide is a wall — nobody knows where to look first, and the discussion degrades into people pointing at different corners of the screen arguing about sequence rather than substance.

So you split it. You make a slide deck with four slides: system overview, flow A, flow B, the edge case. Now you have four diagrams to maintain. When something changes — and it always changes — you update one and forget two. By the third client meeting, the slides are lying.

The better instinct is to show things progressively: here’s the system, now here’s how a request enters, now here’s what the model sees, now here’s where human review kicks in. That’s the mental model you’d build if you were explaining this at a whiteboard. But translating that into a slide deck requires a separate visual for each beat, or increasingly ugly animation, or you just talking through a static diagram while people struggle to follow.

Mermaid — the obvious choice for code-adjacent teams — generates diagrams from text, which is good, but the layout engine is unreliable and the output is consistently ugly. I’ve never shown a Mermaid diagram to a non-technical stakeholder without apologising for it first. That’s not a foundation for alignment.

D2 is different. It has a genuinely good layout engine, the output looks professional, and it handles complex graphs without the node collisions and edge crossings that make Mermaid diagrams hard to read. Once I switched to D2 for client work, the diagram quality problem was solved.

But D2 is still static. You get a good-looking image. You don’t get a walkthrough.

The missing piece

What I wanted was: a D2 diagram that I could step through with a client, one beat at a time, with each step highlighting the relevant components and showing an explanation alongside. The diagram stays on screen — the client can see how each piece fits into the whole — but the focus shifts as we move through the story.

This is what a good whiteboard session feels like. You’re not showing them a completed picture and hoping they absorb it. You’re building understanding incrementally, keeping the structure visible throughout.

I looked for tooling that did this. Nothing did it in a way that worked for how I actually work — text-based source, clean output, no dependency on a hosted service that I’m handing a client diagram to. So I built it.

DiaScope takes a D2 diagram and a YAML narration file and produces a single self-contained .html file. Open it in a browser: diagram on the left, narration panel on the right. Each step highlights the relevant nodes, pans and zooms to them, and shows the explanation text. Press → to advance. Click a node for detail. No server, no login, no setup for the person you’re sending it to.

Here’s what it looks like — a narrated walkthrough of a vLLM deployment:

The input that produces this is deliberately minimal — a .d2 diagram file and a .story.yaml narration sidecar:

steps:
  - id: step-01
    title: "Request enters the preprocessing pipeline"
    body: |
      Raw text is tokenised and stripped of identifying information
      before any model sees it. This step runs synchronously — the
      rest of the pipeline waits here.
    nodes:
      - Ingestion
      - Preprocessor

  - id: step-02
    title: "The model scores candidate outputs"
    body: |
      Three candidate responses are ranked by a fine-tuned scorer.
      The top candidate passes to review; the others are logged
      for evaluation.
    nodes:
      - Scorer
      - CandidateStore

The source files are never touched by DiaScope. The .d2 stays canonical. The .story.yaml is a sidecar. You can regenerate the HTML whenever something changes, and the narration tracks the diagram as long as you keep it updated.

Why this matters beyond the obvious

The walkthrough format solves a specific alignment problem that I run into constantly: the gap between knowing how a system works and being able to get a room of people to the same understanding in 30 minutes.

That gap is expensive. Misaligned stakeholders slow down decisions. Stakeholders who don’t understand the system ask the wrong questions, or — more dangerously — approve things they haven’t actually understood. In regulated environments, “the clinical team signed off” is not a defence if the clinical team was looking at a static diagram that didn’t show the decision boundary clearly.

A narrated walkthrough changes this. You hand a client a link to an .html file before a meeting. They can step through it at their own pace. They arrive with the structure in their head, and the meeting becomes a discussion rather than a briefing.

In my experience this is a qualitative shift in how well stakeholder meetings go. Not incremental — qualitative.

The agent-driven angle

Because DiaScope’s inputs are text — a .d2 file and a .yaml file — agents can generate them directly from code or system descriptions.

DiaScope ships a narrate skill for Claude Code. Install it, point an agent at a codebase, and prompt it naturally:

“Narrate the data ingestion flow in src/pipeline/” “Create a diagram story explaining how the decision engine works”

The agent reads the code, writes the D2 diagram and the .story.yaml, runs diascope build, and hands you the .html. No manual diagram authoring. No YAML by hand.

This matters for the economics of explanation. The question stops being “is this system worth documenting?” and becomes “why wouldn’t we generate a walkthrough for this?” When the marginal cost of an explainer drops toward zero, you can do it for every significant system — not just the ones that get a dedicated documentation sprint.

For teams working under EU AI Act technical documentation requirements, that’s not just convenient. An interactive walkthrough of a system’s data flow and decision logic is a more defensible audit artefact than a Confluence page that drifted from reality six months ago.

Why I open sourced it

The tool worked well enough in client engagements that I thought it was worth making available. The problem it solves — I have a D2 diagram and I want to walk someone through it — is not unique to AI R&D. Any team that explains technical systems to non-technical stakeholders has this problem.

Biolytics is fundamentally about making AI R&D legible: building systems that work, that can be evaluated, and that can be understood by the people who need to make decisions about them. DiaScope is a concrete expression of that — a tool that makes the explanation part of the work, not an afterthought to it.

The code is on GitHub. MIT licensed. Docs and a live example at diascope.biolytics.ai. Install is npm install -g @biolytics.ai/diascope plus d2 on your PATH.

If you make diagrams to explain technical systems to stakeholders, I think you’ll find it useful.

---

Feedback or questions: find me via the contact page or open an issue on GitHub.

Related: Why evaluation discipline matters more than model choice in regulated R&D — same underlying principle, applied to knowing whether your system is working.