How to Generate an Architecture Diagram Using Diagram Design: A Complete Guide

You can generate an architecture diagram using Diagram Design by installing the skill into your AI agent, preparing a Mermaid (.mmd) or draw.io source file, and executing the /import-mermaid or /import-drawio command with the --type=architecture flag.

Diagram Design is a Claude-Code/Factory-Droid skill that transforms structured diagram sources into publication-ready visualizations across 39 supported types. When you need to generate an architecture diagram using Diagram Design, the tool parses your source components, applies architectural layout conventions, and emits self-contained HTML, SVG, or PNG outputs.

Prerequisites: Installing the Skill

Before generating diagrams, you must install the Diagram Design plugin in your agent environment. The skill resides in the skills/diagram-design directory and integrates with Claude Code, Codex, Factory Droid, or Pi.

Install via your agent's plugin marketplace:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Reference: See the installation section in README.md【/cache/repos/github.com/cathrynlavery/diagram-design/main/README.md#L11-L22】.

Step-by-Step Workflow to Generate Architecture Diagrams

Step 1: Prepare Your Source File

Create a source file containing your logical components. Diagram Design accepts either Mermaid files (.mmd or .mermaid) or draw.io files (.drawio).

For Mermaid, define your architecture using flowchart syntax with subgraphs to represent system zones:

flowchart LR
    subgraph Frontend
        UI[UI]
    end
    subgraph Backend
        API[API]
        DB[(Database)]
    end
    UI --> API
    API --> DB

Save this content as architecture.mmd in your working directory.

Step 2: Invoke the Import Command

Use the appropriate import command based on your source format. The system resolves the skill directory automatically—never assume the skill lives in the current working directory【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L41-L44】.

For Mermaid sources:

import-mermaid architecture.mmd --type=architecture --size=slide-16x9 --detail=balanced --variant=dark

For draw.io sources:

import-drawio system.drawio --type=architecture --size=doc-wide --detail=faithful --variant=light

The --type=architecture flag explicitly sets the diagram type, though the skill can infer architecture from flowcharts containing service boxes and directional arrows.

Step 3: Retrieve Your Generated Files

By default, the command writes a self-contained HTML file (e.g., architecture.html) adjacent to your source file. You can request alternative formats using the --format flag:

• --format=svg for scalable vector graphics
• --format=png for rasterized images
• --format=html+png for both formats simultaneously

Non-HTML formats are derived from the HTML base via the export pipeline defined in references/export.md【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/export-diagram.md#L30-L31】.

Understanding the Architecture Rendering Pipeline

Source Extraction and Digest Creation

When you execute an import command, the skill runs internal extractor scripts—scripts/mermaid_extract.py for Mermaid files or scripts/drawio_extract.py for draw.io files. These parsers build a digest containing nodes, edges, and optional zone definitions.

If extraction fails with a non-zero exit code, the error is reported verbatim to aid debugging【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-drawio.md#L41-L44】.

Type Inference and Style Application

The digest's "type candidates" field ranks possible diagram types based on content structure. Architecture diagrams are selected when the grammar matches service-oriented patterns, though you can override this with explicit flags.

The Architecture layout conventions defined in skills/diagram-design/references/type-architecture.md enforce:

• Orthogonal connectors with rounded right-angle bends (mandatory per the style guide)【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/type-architecture.md#L14-L16】
• Zone rectangles for grouping related components
• Bridge/hop primitives for intersecting lines

Output Generation and Fidelity Reporting

After rendering, the command prints a fidelity ledger showing what elements were merged, collapsed, or dropped during the transformation. This transparency helps you assess how closely the output matches your source intent【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L49-L52】.

Programmatic Usage: Direct Python Invocation

For advanced workflows, invoke the extractor directly from Python without the CLI wrapper:

import subprocess
import pathlib

skill_dir = pathlib.Path(__file__).parent / "skills" / "diagram-design"
mermaid_src = pathlib.Path("architecture.mmd")

cmd = [
    "python", str(skill_dir / "scripts" / "mermaid_extract.py"),
    "--input", str(mermaid_src),
    "--type", "architecture",
    "--size", "slide-16x9",
    "--detail", "balanced",
    "--variant", "dark"
]

subprocess.run(cmd, check=True)

This approach writes the output HTML to the same directory as your input source file.

Key Configuration Files

The following files govern architecture diagram generation in the cathrynlavery/diagram-design repository:

File	Purpose
commands/import-mermaid.md	CLI specification, flags (--type, --size, --detail), and required behavior for Mermaid sources
commands/import-drawio.md	CLI specification for draw.io import workflows
skills/diagram-design/references/type-architecture.md	Comprehensive style guide covering layout conventions, connector rules, and zone handling
skills/diagram-design/scripts/mermaid_extract.py	Parser that converts Mermaid syntax into the internal digest format
skills/diagram-design/scripts/drawio_extract.py	Parser handling compressed draw.io formats

Summary

• Diagram Design is an AI agent skill that converts Mermaid or draw.io sources into high-quality architecture diagrams.
• Use /import-mermaid or /import-drawio commands with --type=architecture to trigger the rendering pipeline.
• The system enforces rounded right-angle connectors and orthogonal layouts as mandatory architectural standards.
• Output defaults to HTML but supports SVG and PNG via the export pipeline.
• The fidelity ledger provides transparency about structural transformations applied to your source.

Frequently Asked Questions

What file formats does Diagram Design support for architecture diagrams?

Diagram Design accepts Mermaid files (.mmd or .mermaid) and draw.io files (.drawio) as input sources. The output can be generated as self-contained HTML, SVG, PNG, or a combination of HTML and PNG formats.

Can I override the automatic diagram type detection?

Yes. While the skill infers diagram types from content patterns (such as service boxes and arrows for architecture), you can explicitly set the type using the --type=architecture flag in your import command【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L25-L27】.

Where are the generated files saved?

By default, the skill writes output files (e.g., architecture.html) to the same directory as your source file. You can specify alternative formats like SVG or PNG using the --format flag, which derives the final output from the HTML base.

How do I customize the visual style of the architecture diagram?

Customize the output using three dial parameters: --size (e.g., slide-16x9, doc-wide), --detail (e.g., balanced, faithful), and --variant (e.g., dark, light). The specific architectural styling—including orthogonal connectors and zone rectangles—is governed by the rules in references/type-architecture.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}