How to Use the Diagram-Generator Skill for Architecture Documentation

The diagram-generator skill converts natural-language descriptions, code snippets, and schemas into editable visual models using Mermaid, Graphviz DOT, PlantUML, or SVG, and includes a command-line renderer at skills/diagram-generator/scripts/render_diagram.py to export diagrams for documentation.

The diagram-generator skill in the zhaoxuya520/reverse-skill repository provides a structured approach to creating architecture documentation through code-driven diagrams. By transforming text-based descriptions into visual models, this skill enables teams to maintain version-controlled, editable diagrams alongside their codebase. Whether documenting microservice interactions or high-level system layers, the diagram-generator skill for architecture documentation ensures consistency and clarity across technical documents.

Supported Diagram Languages for Architecture Documentation

The skill supports four distinct diagram families, each optimized for specific architectural documentation needs. According to skills/diagram-generator/SKILL.md (lines 34-48), you should select your target language based on diagram complexity and required precision:

• Mermaid (flowchart TD/LR, sequenceDiagram, stateDiagram-v2, erDiagram, classDiagram) – Best for process flows, decision trees, interaction diagrams, state machines, and database schemas. Most documentation generators render Mermaid natively.
• Graphviz DOT – Ideal for large dependency graphs, network topologies, and package graphs where automatic layout engines improve readability of dense connections.
• PlantUML (@startuml … @enduml) – Use for formal UML diagrams including detailed class, component, and activity diagrams when strict UML compliance is required.
• SVG – Reserved for precise custom graphics when text-based languages cannot express the required layout or visual styling.

Step-by-Step Workflow for Architecture Documentation

Follow this six-step workflow defined in skills/diagram-generator/SKILL.md to generate architecture diagrams from requirements:

1. Identify intent and audience – Clarify whether the document needs a high-level component view, a data-flow diagram, or a C4-style container diagram.

2. Select the diagram family – Consult the decision table in skills/diagram-generator/SKILL.md (lines 34-48). For most architecture overviews, a Mermaid flowchart with sub-graphs or a Graphviz cluster diagram provides optimal clarity.

3. Normalize entities – Convert the architecture description into a list of components, services, databases, queues, external APIs, and boundary labels.

4. Generate concise source – Write the diagram source using the Mermaid generation rules (lines 66-75) or Graphviz rules (lines 77-86). Use stable ASCII IDs (e.g., frontend[Frontend]) and short, readable labels following the "preserve user terminology" rule (line 57).

5. Validate and render – If a static image or PDF is required, invoke the rendering script:

   python "skills/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out architecture.svg

6. Return source and assumptions – Include the raw diagram source in your documentation alongside a brief "Assumptions" note for any inferred relationships.

Architecture Diagram Patterns and Examples

The repository includes practical templates in skills/diagram-generator/references/diagram-patterns.md and working examples in the examples/architecture/ directory.

Layered 3-Tier Components (Mermaid)

Use Mermaid subgraphs to group architectural layers visually. This pattern follows the rules in skills/diagram-generator/SKILL.md (lines 66-75) for flowchart generation:

flowchart TD
    subgraph UI
        web[Web Front‑End]
    end
    subgraph Service
        api[API Gateway]
        auth[Auth Service]
    end
    subgraph Data
        db[(PostgreSQL DB)]
        cache[(Redis Cache)]
    end

    web --> api
    api --> auth
    auth --> db
    auth --> cache

Source file: examples/architecture/three_tier.mmd

C4-Style Container Views (Graphviz DOT)

For C4 architecture models, combine Graphviz clusters for clear boundary definitions. This approach leverages rankdir=LR for left-to-right layouts and subgraph cluster_* for modules as specified in the Graphviz rules (lines 77-86):

digraph G {
    rankdir=LR;
    node [shape=box style=filled color=lightgrey];

    subgraph cluster_frontend {
        label="Web UI";
        style=filled;
        color=lightblue;
        browser [label="Browser"];
    }

    subgraph cluster_backend {
        label="Backend Services";
        api [label="API Service"];
        auth [label="Auth Service"];
    }

    subgraph cluster_storage {
        label="Data Stores";
        db [label="PostgreSQL"];
        cache [label="Redis"];
    }

    browser -> api;
    api -> auth;
    auth -> db;
    auth -> cache;
}

Source file: examples/architecture/c4_container.dot

Microservice Interaction Sequences (Mermaid)

Document service-to-service communication using sequence diagrams. This format clearly shows synchronous calls and response flows between distributed components:

sequenceDiagram
    participant UI as Front‑End
    participant G as API Gateway
    participant A as Auth Service
    participant S as Service B

    UI->>G: Request /login
    G->>A: Validate credentials
    A-->>G: Token
    G->>S: Call protected endpoint
    S-->>G: Data response
    G-->>UI: JSON payload

Source file: examples/architecture/auth_sequence.mmd

Rendering Diagrams for Documentation Output

The skills/diagram-generator/scripts/render_diagram.py script provides command-line rendering capabilities for Mermaid (.mmd), Graphviz (.dot), and PlantUML (.puml) sources. The script supports export to PNG, SVG, and PDF formats.

To render any diagram for inclusion in static documentation:

python "skills/diagram-generator/scripts/render_diagram.py" examples/architecture/three_tier.mmd --format svg --out docs/images/architecture.svg

For batch generation or testing, use the helper script at skills/diagram-generator/scripts/create_sample_diagrams.py to generate sample diagrams across all supported formats.

Essential Reference Files

File	Purpose
skills/diagram-generator/SKILL.md	Full skill description, workflow decision table (lines 34-48), and generation rules
skills/diagram-generator/references/diagram-patterns.md	Reusable Mermaid, Graphviz, and PlantUML templates
skills/diagram-generator/scripts/render_diagram.py	Command-line renderer for converting source files to images
skills/diagram-generator/scripts/create_sample_diagrams.py	Helper utility for generating test diagrams
skills/diagram-generator/README.md	Overview of supported languages and quick-start guide

Summary

• The diagram-generator skill supports Mermaid, Graphviz DOT, PlantUML, and SVG for different architectural visualization needs.
• Follow the six-step workflow in SKILL.md to normalize entities and select appropriate diagram families.
• Use Mermaid subgraphs for layered architectures and Graphviz clusters for C4-style container diagrams.
• Render final diagrams using skills/diagram-generator/scripts/render_diagram.py with --format svg or --format png for static documentation.
• Store raw diagram source alongside documentation to maintain version control and enable future edits.

Frequently Asked Questions

What diagram formats does the diagram-generator skill support?

The skill supports four primary formats: Mermaid for flowcharts and UML diagrams, Graphviz DOT for complex dependency graphs, PlantUML for formal UML specifications, and raw SVG for custom graphics. According to skills/diagram-generator/SKILL.md, Mermaid is recommended for most architecture documentation due to native Markdown rendering support.

How do I render a Mermaid diagram to SVG for my documentation?

Use the command-line renderer located at skills/diagram-generator/scripts/render_diagram.py. Execute python "skills/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg to generate a static SVG file. The script also supports PNG and PDF outputs for different publication requirements.

Can I use the diagram-generator skill for C4 architecture models?

Yes. The skill supports C4-style diagrams through both Mermaid flowcharts for container views and Graphviz DOT with subgraph cluster_* declarations for component views. The examples/architecture/c4_container.dot file demonstrates how to use clusters to represent C4 boundaries with distinct colors and labels.

Where are the diagram templates and patterns stored?

Reusable templates and language-specific patterns are stored in skills/diagram-generator/references/diagram-patterns.md. The examples/architecture/ directory contains working samples including three_tier.mmd, c4_container.dot, and auth_sequence.mmd that serve as starting points for common architecture documentation scenarios.

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