# architecture-diagrams

> Generate architecture diagrams from documentation maps, codebases, or system descriptions. Produces Mermaid, D2, or PlantUML diagrams. Use when user asks to visualize system architecture, create component diagrams, show dependencies, or generate diagrams from a SKILLS_MAP.md or similar documentation index.

- Author: github-actions[bot]
- Repository: donbr/skills
- Version: 20251221040918
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/donbr/skills
- Web: https://mule.run/skillshub/@@donbr/skills~architecture-diagrams:20251221040918

---

---
name: architecture-diagrams
description: Generate architecture diagrams from documentation maps, codebases, or system descriptions. Produces Mermaid, D2, or PlantUML diagrams. Use when user asks to visualize system architecture, create component diagrams, show dependencies, or generate diagrams from a SKILLS_MAP.md or similar documentation index.
license: Apache-2.0
---

# Architecture Diagram Generator

Generate clear, accurate architecture diagrams from documentation maps, codebase analysis, or system descriptions.

## Supported Output Formats

| Format | Best For | Rendering |
|--------|----------|-----------|
| **Mermaid** | GitHub/GitLab README, documentation sites | Native in GitHub, Notion, Obsidian |
| **D2** | Complex layouts, custom styling | d2 CLI or d2lang.com |
| **PlantUML** | Enterprise docs, detailed UML | plantuml.com or IDE plugins |

## Diagram Types

### 1. Component Diagram
Shows system components and their relationships.

```mermaid
graph TB
    subgraph "Document Skills"
        xlsx[xlsx]
        docx[docx]
        pptx[pptx]
        pdf[pdf]
    end

    subgraph "Creative Skills"
        art[algorithmic-art]
        design[canvas-design]
    end

    User --> |"Create spreadsheet"| xlsx
    User --> |"Create presentation"| pptx
```

### 2. Dependency Graph
Shows which components depend on others.

```mermaid
graph LR
    docx --> ooxml.md
    docx --> docx-js.md
    pptx --> ooxml.md
    pptx --> html2pptx.md
    pdf --> forms.md
    pdf --> reference.md
```

### 3. Category Hierarchy
Shows organizational structure.

```mermaid
graph TD
    Skills[Agent Skills]
    Skills --> Doc[Document Skills]
    Skills --> Creative[Creative & Design]
    Skills --> Tech[Development & Technical]
    Skills --> Enterprise[Enterprise & Communication]

    Doc --> xlsx & docx & pptx & pdf
    Creative --> art[algorithmic-art] & canvas[canvas-design]
```

### 4. Flow Diagram
Shows process or data flow.

```mermaid
flowchart LR
    A[User Request] --> B{Semantic Router}
    B --> |"Read Map"| C[SKILLS_MAP.md]
    C --> D{Identify Skill}
    D --> E[Load SKILL.md]
    E --> F[Execute Task]
```

## Workflow

### From a Documentation Map

1. **Parse the map** to extract:
   - Categories (## headers)
   - Components (### headers)
   - Relationships (file references, subfolders)

2. **Choose diagram type** based on intent:
   - "Show me the structure" → Category Hierarchy
   - "What depends on what" → Dependency Graph
   - "How does it work" → Flow Diagram
   - "What are the components" → Component Diagram

3. **Generate diagram code** in requested format

4. **Output as**:
   - Fenced code block (```mermaid)
   - Standalone .mmd/.d2/.puml file
   - Embedded in markdown documentation

### From a Codebase

1. **Analyze structure** using file patterns:
   - Directory hierarchy
   - Import/require statements
   - Package dependencies

2. **Build dependency graph** from imports

3. **Generate appropriate diagram**

## Helper Scripts

### map_to_mermaid.py

Converts a SKILLS_MAP.md to a Mermaid diagram:

```bash
python scripts/map_to_mermaid.py SKILLS_MAP.md --type hierarchy --output diagram.md
python scripts/map_to_mermaid.py SKILLS_MAP.md --type dependencies --output deps.md
```

**Options:**
- `--type`: `hierarchy`, `dependencies`, `components`, `flow`
- `--output`: Output file path (default: stdout)
- `--direction`: `TB`, `LR`, `BT`, `RL` (default: TB)

## Best Practices

1. **Keep diagrams focused** - One concept per diagram
2. **Use consistent naming** - Match names from source docs
3. **Add context** - Include a title and brief description
4. **Choose appropriate detail level** - Don't show every file, group related items
5. **Use subgraphs** - Group related components visually

## Example: Skills Repository Architecture

```mermaid
graph TB
    subgraph "Specification"
        spec[agent-skills-spec.md]
        auth[skill-authoring.md]
        client[skill-client-integration.md]
    end

    subgraph "Document Processing"
        xlsx[xlsx]
        docx[docx]
        pptx[pptx]
        pdf[pdf]
    end

    subgraph "Creative & Design"
        algo[algorithmic-art]
        canvas[canvas-design]
        frontend[frontend-design]
        brand[brand-guidelines]
        theme[theme-factory]
        gif[slack-gif-creator]
    end

    subgraph "Development"
        mcp[mcp-builder]
        skill[skill-creator]
        artifacts[web-artifacts-builder]
        test[webapp-testing]
    end

    subgraph "Enterprise"
        comms[internal-comms]
        coauth[doc-coauthoring]
    end

    spec --> auth
    spec --> client
    auth --> skill

    style spec fill:#e1f5fe
    style auth fill:#e1f5fe
    style client fill:#e1f5fe
```

## Keywords

architecture diagram, mermaid, d2, plantuml, component diagram, dependency graph, visualization, system design, documentation map, SKILLS_MAP