Turn Code, Terraform and Diagrams into a C4 Model with MCP - Archyl Blog

The blank canvas is a lie: your architecture is already written down in Structurizr files, Terraform modules, Mermaid diagrams and README files. Connect an AI agent to Archyl's MCP server and turn all of it into a living C4 model — without redrawing a single box.

Turn Code, Terraform and Diagrams into a C4 Model with MCP

The hardest part of architecture documentation isn't drawing boxes. It's that by the time you open the tool, your architecture already exists — scattered across five places that don't talk to each other.

A Structurizr DSL file someone maintained for eight months. Mermaid diagrams in a dozen READMEs. Terraform modules that describe your real infrastructure better than any diagram ever did. A PlantUML export from the tool you used before. And the codebase itself, the only source that never lies.

On Saturday I showed how to migrate a Confluence space into Archyl with two MCP servers and a prompt. Today, the same trick with a bigger prize: importing the architecture itself.

Two paths, pick per source

First, the built-in paths: if your repository is connected to Archyl, AI Discovery analyzes the code and proposes a full C4 model — systems, containers, components, relationships — that you review and approve. And if you're coming from another C4 tool, Structurizr DSL, LikeC4 and IcePanel exports already have a one-click importer. When either of those fits, start there.

The MCP path is for everything else: the sources Discovery can't see. Diagrams-as-code files, infrastructure definitions, that architecture page in someone's wiki, or a repo on a private server. Archyl's MCP server exposes the full write surface of the C4 model — create_system, create_container, create_component, create_relationship, set_element_technologies, create_adr — so any agent that can read your source can write your model.

Setup is the same one-liner as Saturday:

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

Recipe 1 — Structurizr, Mermaid, PlantUML

Diagrams-as-code is the easiest win, because the semantics are already explicit. For a standard workspace.dsl, the one-click importer above is faster — the agent earns its keep for Mermaid and PlantUML (no importer exists), DSL variants the importer can't parse, or when you want to merge selectively into a project that already has a model. Open the repo in Claude Code and:

Read workspace.dsl at the root of this repo. Recreate the model in
my Archyl project "Aurora Commerce":

- softwareSystem → create_system (mark external ones as external_system)
- container → create_container under the right system, keep the
  technology field
- every relationship → create_relationship with its description
- don't invent anything that isn't in the DSL; list anything you
  couldn't map

Then read back the model with list_systems and list_containers and
show me a summary so I can check nothing was lost.

The read-back step at the end is the habit worth keeping: the agent verifies its own import against the live model instead of assuming it worked.

Recipe 2 — Terraform

Your infrastructure code knows things your diagrams forgot. Point the agent at your Terraform and let it work at the right altitude:

Read infra/ in this repo. Model the deployment-level architecture
in Archyl: managed services (RDS, SQS, S3, CloudFront...) become
containers or external systems, one per real service — not one per
resource. Wire the relationships from IAM policies, security groups
and environment variables. Tag everything you create with "terraform"
so I can filter the imported layer later.

The "not one per resource" line is doing real work. A naive importer turns 400 Terraform resources into 400 boxes. An agent understands that a DB instance, its subnet group and its parameter group are one container called Orders Database.

Recipe 3 — the codebase itself

No DSL, no diagrams, repo not connected to Archyl? The agent is already sitting in your code. Ask it to propose the model bottom-up — services from the deploy manifests, components from the package structure, relationships from the HTTP clients and queue producers it finds. This is AI Discovery's job done by hand, and it's the right fallback when Discovery can't reach the source.

Recipe 4 — diagrams trapped in your wiki

Combine both MCP servers from Saturday's post: the agent reads the architecture pages through Atlassian's MCP server, extracts the described systems and flows, and writes them into Archyl. The wiki page that describes your event pipeline becomes an actual, navigable model of it — and the page itself comes along as linked documentation.

Import is the boring part — here's the point

The day after the import is why you did it. Because the model went in through MCP, it stays reachable through MCP:

  • Your agents query it while coding — "which containers talk to the payments database?" is one tool call away.
  • New services get added by the same agents that build them, so the model tracks reality instead of decaying.
  • Drift scoring and conformance rules run against a model that actually matches your systems.

One honest rule to close: the agent proposes, you review. Import one system at a time, read the summaries, and prune what doesn't belong — the same discipline as any code review. The model you end up with is only as good as the sources you fed it, and you're the one who knows which of the five sources was telling the truth.

Your architecture already exists. Stop redrawing it — import it. The full tool list is in the MCP server docs.