DEV Community

Cover image for Turn any repo into a shareable architecture board with Claude Code (step by step)
Sheel Khanna
Sheel Khanna

Posted on Originally published at drawlyhub.com

Turn any repo into a shareable architecture board with Claude Code (step by step)

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)