Stop Drawing Diagrams — Generate Them

How five Claude Code skills turned architecture visualisation from a maintenance burden into a byproduct of good note-keeping.

Photo by Maxim Berg on Unsplash

Diagram Rot

Every architecture team has one. The system landscape diagram was accurate for about three weeks after someone spent a full day in Lucidchart getting the boxes right. Then a service was renamed, two integrations were added, a database was migrated — and nobody updated the picture. Six months later, a new joiner uses it to understand the estate and makes decisions based on a key piece of outdated information.

This is called Diagram Rot, and it is the default outcome for hand-drawn architecture diagrams. Not because architects are lazy, but because the economics are wrong. A diagram lives in Confluence, SharePoint or some SaaS diagramming tool, completely disconnected from the system definitions, integration specs, and architecture decisions it is supposed to represent. Updating it means context-switching into a visual editor, remembering which boxes changed, and hoping you haven’t introduced a new inaccuracy in the process.

The result: architects learn not to trust diagrams, stakeholders learn not to read them, and the whole practice of visual architecture documentation quietly degrades into theatre.

Diagrams Are Outputs, Not Inputs

The fix is not “be more disciplined about updating diagrams.” The fix is to stop treating diagrams as primary artefacts and start treating them as derived views.

If your system definitions live in structured, machine-readable notes — with frontmatter that describes integrations, containers, technologies, and relationships — then a diagram is just a query over that data. Change the data, regenerate the diagram. The diagram is always as current as the last time you asked for it.

If the diagram update is part of your DevOps workflow, then your diagrams will always be in sync with the version you have deployed.

This is architecture-as-code applied to visualisation — and it is practical now, not theoretical, because of Claude Code skills.

Over the past few months, I have built five Claude Code skills that turn those notes in Repos into diagrams — C4 models, system landscapes, data flows, dependency graphs, and interactive canvas views. The skills are open source and published in the ArchitectKB template repository. Here is how they work and why I think this approach matters.

Five Skills for Five Jobs

/diagram — The Multi-Format Generator

The /diagram skill is the workhorse. It supports eight diagram types (C4 context, C4 container, C4 component, system landscape, data flow, AWS architecture, integration pattern, dependency graph) across four output formats:

• Mermaid — renders natively in Obsidian, Git-friendly, fast iteration
• PlantUML — better layout control for complex diagrams with 15+ elements
• Python diagrams — professional PNG output with AWS/GCP/Azure icons
• Canvas — interactive Obsidian Canvas (JSON) for spatial exploration

You type /diagram c4-context CustomerPortal and the skill prompts for scope, included systems, and styling preferences. Then it generates the diagram, renders it, and — this is the part that matters — runs a validation gate.

The validation gate checks six criteria against the rendered output:

If any criterion fails, the skill is revised and re-rendered automatically. It reads the PNG back and inspects it visually. This loop continues until all six criteria pass. You don’t see the failed attempts — you see the clean result.

/c4-diagram — The Data-Driven Approach

The /c4-diagram skill is where the “diagrams as derived views” idea becomes concrete. It reads the c4: section from a System note’s frontmatter:

c4:
 description: Central data integration and analytics platform
 boundary: internal
 actors:
 - name: Data Engineer
 description: Builds and maintains pipelines
 - name: Business Analyst
 description: Consumes reports and dashboards
 containers:
 - name: Ingestion Service
 technology: Python/Kafka
 description: Receives events from source systems
 - name: Processing Engine
 technology: Apache Spark
 description: Transforms and enriches data
 - name: Analytical Store
 technology: PostgreSQL
 description: Serves queries and reports
 externalRelationships:
 - target: ERP System
 description: Receives business events
 technology: Kafka
 - target: API Gateway
 description: Exposes data products
 technology: REST/JSON

From this, /c4-diagram DataPlatform generates a complete C4 context diagram. /c4-diagram DataPlatform container generates the container view. /c4-diagram DataPlatform both generates both.

The architect never specifies the layout. The skill handles declaration order (actors first, then the system boundary, then external systems, then relationships), applies tier-based positioning, and selects the right output format based on element count. Under 10 elements: Mermaid. Over 15: PlantUML with directional hints. Between 10 and 15: the skill asks.

The critical point is this: when you update the System note’s frontmatter — say, adding a new container or changing an integration target — the next /c4-diagram invocation produces a diagram that reflects reality. No visual editor. No remembering which box to move.

/diagram-review — Automated Quality Assurance

The /diagram-review skill takes any architecture diagram (PNG, screenshot, Mermaid render) and performs a structured analysis. It dispatches parallel agents to extract components, map relationships, analyse architecture patterns, identify risks, and assess readability.

The output is a structured report covering what the diagram shows, what patterns it reveals, what’s missing, and what could be improved. This is useful not just for diagrams you generate, but for reviewing diagrams that arrive in vendor proposals, consultant deliverables, or inherited documentation.

/canvas — Interactive Spatial Views

The /canvas skill generates Obsidian Canvas files — JSON documents with positioned nodes and edges. Unlike rendered images, Canvas files are interactive: click a system node to navigate to its System note, rearrange elements during a workshop, and add annotations inline.

Canvas is particularly effective for system landscape views where you want to explore rather than present. The skill handles the JSON structure, colour-coding (red for critical systems, blue for external, green for healthy), and linking to vault notes.

/dependency-graph — Risk Analysis

The /dependency-graph skill answers the questions that matter in change advisory boards: what depends on what, where the single points of failure are, and what the blast radius is if a system goes down.

It reads System notes tagged with criticality levels, maps integration dependencies, and generates a directed graph with critical path highlighting. The output includes a risk summary identifying the longest dependency chains and the systems with the highest fan-in (most dependents).

Opinions Enforced by Code

The skills are deliberately opinionated. Architecture diagrams fail most often not because the tools are bad, but because the drawing choices are bad. These skills encode specific rules:

Box vs Label.

At the C4 context level, only systems, actors, and devices should be boxed. Authentication mechanisms, network paths, protocols, and policies are edge labels or annotations. The heuristic: if you can’t send a request or log into it, it’s probably a label.

Layout direction.

Top-to-bottom for single linear flows and hierarchies. Left-to-right when the diagram has branching parallel paths. The skill is selected automatically based on the data shape.

Cluster nesting.

Maximum one level of clusters at C4 context (cloud boundaries only). Up to two levels at the container level. Three at the component level if needed. No clusters for logical groupings that aren’t real deployment boundaries.

Edge crossings.

Research by Purchase et al. found that edge crossings are the single strongest predictor of diagram comprehension difficulty. The validation gate enforces a target of fewer than five crossings for complex diagrams and zero for simple ones.

These are not suggestions. They are checked programmatically after every render.

What This Doesn’t Solve

Complex custom layouts still need manual refinement. If you need a specific spatial arrangement for a presentation — systems positioned to mirror a physical data centre layout, for example — you will need to adjust the output. The skills produce readable defaults, not pixel-perfect designs.

The approach also assumes you have structured data to draw from. If your system definitions are unstructured prose, the data-driven /c4-diagram skill has nothing to work with. The investment is in the notes, not the diagrams.

And Mermaid has real limitations. The Dagre layout engine provides limited control over element positioning. For diagrams with more than 15 elements or persistent edge crossings, PlantUML or the Python diagrams library produces better results. The skills know this and suggest format switches when appropriate.

AI cannot do the important thinking for you.

When you don't have experts, you won’t have expertise

There is a time and place for automation, and it is not at the initial design stages. AIs thrive when there is a lot of context. When we start designing solutions, this is exactly where the lack of context becomes apparent. During the design process, that context is discovered, defined and refined. Yes, AIs can help here, but in different ways, such as assisting in research. But ultimately, if you are designing a system that humans will use, a human should have the final say. Why is that? For all the knowledge an AI accumulates, it does not live in our world, does not have the same experiences and pressures, so this is where the line is drawn.

Getting Started

The skills, along with sample System notes and a comprehensive Diagram and Visualisation Guide, are published in the ArchitectKB template repository. Clone it, install Claude Code, and run /diagram c4-context on one of the sample systems to see the workflow in action.

Prerequisites:

• Claude Code (Anthropic’s CLI for Claude)
• Python 3.8+ with the diagrams package (for PNG output)
• Graphviz (brew install graphviz on macOS)
• Obsidian 1.5+ (for Mermaid rendering and Canvas support)

Start with one system. Write the frontmatter. Generate the diagram. Watch it update when you change the note. Once you have experienced that loop — data in, diagram out, no drawing required — opening Lucidchart feels like a chore you no longer need.

References

• ArchitectKB Template Repository — Open source Obsidian vault template with all five diagram skills
• C4 Model — Simon Brown’s approach to software architecture diagramming
• Purchase, H. C. (2002). “Metrics for Graph Drawing Aesthetics.” Journal of Visual Languages and Computing, 13(5), 501–516. — Research on edge crossings and diagram comprehension
• Claude Code Documentation — Anthropic’s CLI tool