# How to Use the Diagram-Generator Skill for Architecture Documentation

> Learn to use the diagram-generator skill to create editable architecture diagrams from text, code, and schemas. Export visuals using Mermaid, Graphviz, and more for effortless documentation.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

   ```bash
   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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md) (lines 66-75) for flowchart generation:

```mermaid
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):

```dot
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:

```mermaid
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md) | Full skill description, workflow decision table (lines 34-48), and generation rules |
| [`skills/diagram-generator/references/diagram-patterns.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/references/diagram-patterns.md) | Reusable Mermaid, Graphviz, and PlantUML templates |
| [`skills/diagram-generator/scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/render_diagram.py) | Command-line renderer for converting source files to images |
| [`skills/diagram-generator/scripts/create_sample_diagrams.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/create_sample_diagrams.py) | Helper utility for generating test diagrams |
| [`skills/diagram-generator/README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.