AI Agents Guide

Can an AI draw an architecture diagram from a repository: the two honest answers

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The question gets asked as one question and has two answers, because two different mechanisms are hiding behind it. One is an agent that has already read your code and needs somewhere to put the result. The other is a parser that reads the repository on a schedule with no model deciding what exists. They fail in opposite directions, and the useful setup runs both.

Try it free
7 min readFor engineers deciding whether to point an agent at the code or connect the repo itself

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

137/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Two mechanisms, routinely confused

In the agent path, a coding assistant like Claude Code or Cursor reads the repository on your machine, decides what the architecture is, and calls tools to draw it. The reading is a language model reading files, so it is fast, flexible, and capable of being wrong in confident ways.

In the sync path, a parser reads declared structure from the repository and rebuilds the diagram from it on a schedule. It cannot invent a service, because it only draws what a file declares. It also cannot understand anything that is not declared.

The distinction matters for one practical reason. The agent draws when you ask. The parser draws when the branch changes. If you only run the first, the diagram is exactly as current as your last session with an agent.

The agent path: it already read the code, the problem is the output

Ask any model for a diagram and it hands back Mermaid or PlantUML. That output is text the model never sees rendered, so overlap, grouping, and layout are guesses. Past a dozen boxes it produces something a human has to redraw before showing anyone.

Connecting a diagram tool over MCP changes the shape of the work. The agent stops writing a picture in one shot and starts operating a canvas: adding nodes, connecting them, grouping into zones, running a layout, then measuring and validating the result. The Datadef MCP server exposes 36 tools for exactly this, 9 whole-diagram tools such as create_diagram and export_diagram plus 27 canvas tools for the fine work, and a design guide the agent should read before its first call.

What leaves your machine is the structure the agent decided to draw: node names, zones, edges, column names where you asked for lineage. The source is never requested, because no tool accepts it.

> Read this repo and diagram how our data flows.

⏺ Read - dbt_project.yml, models/staging/*.sql (14 files)
⏺ Read - terraform/kinesis.tf, terraform/redshift.tf
⏺ get_design_guide - zone and edge rules
⏺ create_diagram - "Order Analytics Platform"
⏺ canvas_add_nodes - 4 zones, 16 nodes
⏺ canvas_connect_nodes - 11 labelled edges
⏺ canvas_layout_canvas - layered
⏺ canvas_validate_canvas - no orphans, no overlaps
⏺ export_diagram - png

The sync path: nothing guesses what exists

Connect the repository read-only from GitHub, GitLab, or Azure DevOps, pick a branch or tag, and the diagram plus an architecture doc regenerate daily. For Terraform repositories every .tf and .tfvars file is parsed directly: no init, no state file, no cloud credentials. Modules become zones, registry module calls keep their source and version, and per-environment counts come from the tfvars rather than from a guess.

The parse also declines to draw things, which is what makes it useful rather than exhaustive. Every resource type carries a weight in the parser catalog: major becomes a box, minor rolls up into a counted node when there is no room, and glue is counted but never drawn. IAM roles, policy attachments, log groups, and metric alarms are glue, as is every resource from the random, null, local, time, tls, archive, template, external and terraform providers. That is why a repository holding more identity objects than real resources still produces a diagram of the resources.

Two properties make this the half that survives contact with a real team. Node identity is derived from the declared address, so a re-sync updates the picture instead of reshuffling it, and hand-moved nodes keep their positions. And a commit whose parsed structure hashes to the same value as the previous one skips generation entirely, so a documentation-only commit costs nothing and produces no new version.

The two paths meet at the same canvas. An agent can check freshness with repo_status and trigger a sync with repo_refresh, so the session that changed the infrastructure can also bring the picture forward. See how repository sync works.

What neither path can do

Neither reads runtime. Which path carries the traffic, what is deployed but deprecated, which queue is actually empty, none of that is in the source or in a parse of it. Neither knows intent either: why the boundary is where it is, what the team plans to retire, which system is owned by another department.

That is not an argument against generating the diagram. It is an argument for treating the generated version as the accurate base layer and adding the human layer on top: zone labels that name the domain, notes on the deprecated path, an annotation where the manual step lives. More on the boundary in what an agent can infer from code.

A quick way to test either path

Generate once, then ask a person who joined the team last month to find one thing they know is wrong. If they cannot, the diagram is good enough to publish. Try it on the scratch canvas with no account first.

FAQ

Can an AI agent really produce a usable architecture diagram from a codebase?

It can produce a good draft. The reading part is genuinely strong, because a coding agent already has the repository in context. The weak part is the drawing: a model asked for diagram code writes text it never sees rendered, so layout and grouping are guesses. Giving the agent real canvas tools, including a validation step it can call, is what turns the draft into something presentable.

Does the diagram tool need a copy of my source code?

Over MCP, no. The agent reads the repository locally and sends only the structure it chose to draw: node names, zones, edges, and column names for lineage. There is no tool that accepts source files. Repository sync is the separate case where you deliberately connect a read-only repository so it can be parsed on a schedule.

Which is more accurate, the agent or the repository parse?

The parse, for anything it covers, because it only draws what a file declares and cannot invent a component. The agent is broader, since it can read application code, configuration, and comments that no parser models, but it will occasionally produce a plausible node with nothing behind it. Reviewing node by node against file paths catches that.

Will the diagram stay up to date on its own?

Only in the sync path. Tools invoked by an agent run inside a session and nothing runs between sessions, so an agent-drawn diagram is as current as the last time somebody asked. A connected repository regenerates its diagram and its architecture doc daily and on demand.

How long does the first generation take?

Generation from a prompt typically completes in one to three minutes. Over MCP, create_diagram waits up to thirty-five seconds for the finished canvas and otherwise hands back the diagram id to poll, so a slow generation does not block the agent. A Terraform repository parse itself takes seconds, with the first diagram usually on screen a couple of minutes after connecting.