Skip to main content

7. Diagrams & Visuals

Note: The video covers material not in the guide below — please watch in full.

Action Step

Complete this before moving on.

Follow along with the video — this is a workshop, not a lecture. Install the Excalidraw, draw.io, and Mermaid diagram extensions in VS Code. Then use Claude Code to create diagrams programmatically in all three formats. Once you've explored the demos, take your kickoff prep document from the earlier training and have Claude Code generate a multi-tab draw.io file with diagrams relevant to the client. Bonus: if you can crack how to preview Mermaid diagrams in VS Code, record a Loom and share it — you'll be forever remembered in Academy.

Architect Kylee cracked the bonus challenge.

She figured out how to preview Mermaid diagrams in VS Code — and recorded the Loom to prove it. As promised: forever remembered in Academy.

Comment in Slack

Post your answer in your onboarding channel.

What was your biggest takeaway(s) from this training?

Training Guide

You've been building documents — prep docs, decks, recaps, skills. All text. But sometimes the deliverable that makes a client go "wow" isn't a document. It's a diagram. An org chart, a tech stack map, an engagement timeline, a risk matrix.

The thing is, you don't need Visio or Lucidchart or a graphic design background. You can create all of this programmatically — meaning Claude Code writes the underlying code, and VS Code renders it as a visual.

(Three tools, three formats, all free and open source)

The Three Diagram Formats​

There are three major open-source diagram formats you can create inside VS Code:

Excalidraw — uses JSON underneath. Has a hand-drawn, sketch-like aesthetic. Files end in .excalidraw. Renders in VS Code via extension and natively on GitHub. Good for whiteboard-style visuals.

Mermaid — uses its own text-based language (not JSON). Files end in .mmd or get embedded in markdown. Clean, professional, auto-laid-out. You describe the relationships and it figures out the positioning. Also renders natively in GitHub markdown.

draw.io — uses XML (specifically MX Graph XML). Most professional and polished of the three — looks like something out of Visio or Lucidchart. Renders in VS Code via the draw.io extension. Has multi-tab support, so you can put multiple diagrams in one file.

All three are fully open source with MIT licenses. You own your files, you can render them anywhere, and you're never locked into a paid service. The paid versions of each tool only add cloud collaboration — the core tooling is free.

(The interesting part: since these are all just text-based code formats, Claude Code can generate them)

Install the Extensions​

Open VS Code and go to the Extensions marketplace. Search for and install:

  1. Excalidraw — renders .excalidraw files as interactive whiteboards
  2. draw.io Integration — renders .drawio files with a full visual editor
  3. Mermaid diagram — preview support for .mmd files

Once installed, any file in the right format opens directly as a visual — no browser needed.

Create Demo Diagrams​

Open Claude Code and tell it what you want. Give it context about what kind of company you're working with so the demos are relevant, not generic.

Claude Code generates the files in your folder. You'll see the difference between formats immediately — Excalidraw feels like a whiteboard sketch, draw.io looks polished and professional, and Mermaid auto-lays out clean relationship diagrams.

(draw.io is the standout for client-facing work)

The Collaboration Workflow​

Here's where it gets powerful. When you open a draw.io file in VS Code and drag shapes around, resize boxes, or add arrows — it's writing to the underlying XML in real time. That means:

  1. You sketch a rough layout in the visual editor
  2. Save it
  3. Tell Claude Code to read the file, understand the structure, and polish it
  4. Claude refines the diagram programmatically — fixing alignment, adding detail, making it presentation-ready

You can go back and forth. Sketch rough, let AI polish. It's a collaborative workflow between your visual instincts and Claude's ability to write precise code.

Multi-Tab Diagrams​

draw.io supports multiple tabs in a single file — like sheets in a Google Spreadsheet. Each tab is a separate diagram element in the XML. Claude Code can generate a single .drawio file with five or six different diagrams inside, each on its own tab.

For the kickoff prep document, the tabs that make sense are: a stakeholder map, a pain points matrix, an engagement timeline, a tech stack assessment, and a risk register. Each one gives a different stakeholder a visual they can immediately use.

Sharing Diagrams​

Once you've built a diagram, you need to get it in front of the client. A few options:

  • Push to GitHub — GitHub renders draw.io natively. Anyone with the link can view the diagram directly in the browser. They can even edit it without cloning the repo.
  • Export to SVG or PNG — drop it into a Google Doc, a slide deck, or an email.
  • diagrams.net — the free web version of draw.io. Upload the file and share a link. No paid tier needed.
  • Embed in Notion — if the client uses Notion, draw.io files embed directly.

You never have to pay for anything. The entire business model for these tools is built on enterprise integrations — the core product stays free.

What You Just Did​

You created professional diagrams without opening a design tool, without drawing anything by hand, and without paying for software. You gave Claude Code a client document and it produced visual deliverables — org charts, timelines, risk matrices — that you can edit, share, and iterate on.

This was a kickoff prep doc. Now imagine running this on a full project implementation — mapping out CRM architectures, data flows, integration diagrams. The same workflow scales to anything.