All posts

Turn Any Repo into a Shareable Architecture Board with Claude Code (Step by Step)

· Sheel Khanna

Most architecture diagrams are stale the day after they're drawn, because drawing them by hand is tedious and nobody wants to redo it. Here's a way to get a first draft in about a minute, from the code you already have open — and end up with a board your team can actually edit, not a picture you'll never touch again.

The short version: connect Claude Code to DrawlyHub over MCP, point it at a repo, and ask it to document the thing. This is the step-by-step. (If you want the why — why a board beats a Mermaid snippet — I wrote that up here; this post is the how.)

What you'll build

A DrawlyHub board with a shareable URL: your services as boxes, the request path and data stores wired up with labelled connectors, laid out on a frame you can pan, zoom, and drag. Made from your actual code — you don't describe the boxes, the agent finds them.

Before you start

  • Claude Code installed and working in a terminal. (Any MCP-capable client works; the commands below are Claude Code's.)
  • A repository open — one you know well, so you can sanity-check what the agent inferred.
  • A DrawlyHub account. Driving boards from an agent is a Pro feature; there's a two-week trial with no card if you just want to try the flow.

Step 1 · Add the MCP server

MCP is the standard that lets an AI client discover a tool's capabilities and call them with your authorization — so instead of printing diagram syntax, the agent calls real tools like "create a board." Add DrawlyHub as a server:

claude mcp add --transport http \
  drawlyhub https://drawlyhub.com/mcp

Your DrawlyHub Profile page shows the exact command for your account, so you can copy it rather than type it.

Step 2 · Connect and approve it

Run /mcp in Claude Code and choose drawlyhub. Your browser opens DrawlyHub's consent page — sign in if asked, then Allow.

That consent screen is the whole security model, so it's worth understanding what you're agreeing to:

  • The client registers itself automatically (open Dynamic Client Registration, RFC 7591 — the standard for MCP), so there's no API key to paste or leak.
  • You approve what the agent may do, in your own browser, before it touches anything.
  • Once approved, the agent acts as you: it can only reach the boards your own account can. A client that isn't a first-party app is labelled unverified, so a look-alike can't impersonate something you trust.
  • You can revoke it any time from Profile ▸ Connected apps — it's a scoped, revocable session, not a standing key.

Step 3 · Ask it to document the repo

Open the project and ask in plain words:

Build a DrawlyHub board that documents this repository.

Claude Code reads the code it already has access to — entry points, services, the data layer — composes the whole diagram as one board document, validates it, and creates it. A few seconds later it hands back a URL. Open it: the boxes are there, wired up, on a frame you can move around.

Here's what the agent is doing behind that one sentence, if you're curious:

describe_format()              # learn the board schema
# ... agent reads your repo and composes the whole board as one document ...
validate_board(document=board) # dry-run: catches a dangling link before anything is created
create_board(document=board)   # creates it, returns the board's URL

Connectors reference box ids, so they stay attached when you move a box later — which matters for the next step.

Step 4 · Refine it — by dragging, not re-prompting

This is the part you can't do with a snippet. The agent gave you a draft; now make it yours:

  • Move things. Grab a box and drag it; the connectors follow.
  • Annotate. Drop a sticky note — "autoscaling TBD", "owned by payments team" — right on the canvas.
  • Iterate with the agent. Ask it to change the board in place:

Add a Redis cache between the API and the database, and a queue for the worker.

It uses regenerate_board, which saves a version first, so you can always roll back.

Mix the two freely: let the agent do the bulk placement, then nudge the three boxes it got wrong by hand.

Step 5 · Share, present, export

  • Share a link. View-only for anyone, or give a teammate edit access. Link it from the PR or the ticket.
  • Present it. Boards organize into frames (think slides), so one board can hold the request path, the data model, and the deploy pipeline — step through them frame by frame.
  • Export. PNG or SVG of a frame, or the whole board as a .drawly file you can re-import later.

Prompts worth keeping

Start broad, then narrow. A few that work well:

Goal Prompt
Whole-system overview Build a DrawlyHub board that documents this repository.
Just the hot path Draw only the request path for a logged-in user, from the edge to the database.
Data model Create a board showing the main entities and how they relate.
A specific flow Add a frame with a sequence diagram of the login flow. (The agent can drop a Mermaid container when text beats boxes — it renders from code but lives on the same canvas.)
Tidy up Group the AWS services into a labelled zone and align them.

Troubleshooting & good to know

  • It got the shape wrong. On an unfamiliar or sprawling repo, the agent infers — check what it drew against what you know, and correct it with a follow-up prompt or by hand. It's a head start, not an architect.
  • It's a whiteboard, not a modeling tool. Great for thinking visually, fast. If you need validated infrastructure-as-code or a cost estimate, this isn't that.
  • Want tighter layouts? There's a small skill that teaches an agent DrawlyHub's layout rules, at /drawly/skill — point your agent at it and the boards come back cleaner.
  • The toolbox behind the consent screen is small and named: list_boards, get_board, validate_board, create_board, regenerate_board. Nothing else.

Try it

  • See the canvas first on the live demo board — no account needed.
  • Then run the three steps above against a repo you know, and see whether it got the architecture right.

The whole point is that the output is the shared artifact — built from the code on your disk, editable by your team, living at a URL instead of evaporating in a chat transcript. If you draw something good with it, I'd like to see it.

Open the demo board No account needed.