architecture-diagram · diff

v1.0.0 to v1.0.0

14 added, 3 removed. Audit A to A.

---

name: architecture-diagram

description: Dark-themed SVG architecture/cloud/infra diagrams as HTML.

version: 1.0.0

tags:

- architecture

- diagrams

- SVG

- HTML

- visualization

- infrastructure

- cloud

author: ported

---

# Architecture Diagram Skill

Generate professional, dark-themed technical architecture diagrams as standalone HTML files with inline SVG graphics. No external tools, no API keys, no rendering libraries — just write the HTML file and open it in a browser.

## Scope

**Best suited for:**

- Software system architecture (frontend / backend / database layers)

- Cloud infrastructure (VPC, regions, subnets, managed services)

- Microservice / service-mesh topology

- Database + API map, deployment diagrams

- Anything with a tech-infra subject that fits a dark, grid-backed aesthetic

**Look elsewhere first for:**

- Physics, chemistry, math, biology, or other scientific subjects

- Physical objects (vehicles, hardware, anatomy, cross-sections)

- Floor plans, narrative journeys, educational / textbook-style visuals

- Hand-drawn whiteboard sketches (consider `excalidraw`)

- Animated explainers (consider an animation skill)

If a more specialized skill is available for the subject, prefer that. If none fits, this skill can also serve as a general SVG diagram fallback — the output will just carry the dark tech aesthetic described below.

Based on [Cocoon AI's architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT).

## Workflow

1. User describes their system architecture (components, connections, technologies)

2. Generate the HTML file following the design system below

3. Save with `write_file` to a `.html` file (e.g. `~/architecture-diagram.html`)

- 4. User opens in any browser — works offline, no dependencies

+ 4. **If the user wants to view/share the diagram in chat (web console, WeCom / 企业微信, DingTalk, Feishu, Telegram, ...): call `render_html_image(filePath="<the .html path>", filename="<name>")`** and return the markdown link it produces. IM channels can only deliver rasterised images natively, so a PNG is required for the diagram to appear inline rather than as a dead link or a file attachment.

+ 5. Otherwise, the user opens the `.html` directly in a browser — works offline, no dependencies.

### Output Location

Save diagrams to a user-specified path, or default to the current working directory:

```

./[project-name]-architecture.html

```

- ### Preview

+ ### Delivering through chat / IM channels

- After saving, suggest the user open it:

+ When the current channel is anything other than a local browser session, follow up `write_file` with:

+ ```

+ render_html_image(filePath="./architecture-diagram.html", filename="architecture")

+ ```

+ This returns a `/api/v1/files/generated/<id>` URL with `image/png` MIME. The channel layer detects the image MIME and uploads the PNG as a native image message (so it renders inline in WeCom / DingTalk / Feishu / Telegram / Web). Without this step, an `.html` artifact reaches IM channels as either a dead markdown link or, at best, a non-previewable file attachment.

+ ### Local preview

+ After saving, the user can open the `.html` directly:

```bash

# macOS

open ./my-architecture.html

# Linux

xdg-open ./my-architecture.html

```

## Design System & Visual Language

### Color Palette (Semantic Mapping)

Use specific `rgba` fills and hex strokes to categorize components:

| Component Type | Fill (rgba) | Stroke (Hex) |

| :--- | :--- | :--- |

| **Frontend** | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |

| **Backend** | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |

| **Database** | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |

| **AWS/Cloud** | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |

| **Security** | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |

| **Message Bus** | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |

| **External** | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |

### Typography & Background

- **Font:** JetBrains Mono (Monospace), loaded from Google Fonts

- **Sizes:** 12px (Names), 9px (Sublabels), 8px (Annotations), 7px (Tiny labels)

- **Background:** Slate-950 (`#020617`) with a subtle 40px grid pattern

```svg

</pattern>

```

## Technical Implementation Details

### Component Rendering

Components are rounded rectangles (`rx="6"`) with 1.5px strokes. To prevent arrows from showing through semi-transparent fills, use a **double-rect masking technique**:

1. Draw an opaque background rect (`#0f172a`)

2. Draw the semi-transparent styled rect on top

### Connection Rules

- **Z-Order:** Draw arrows *early* in the SVG (after the grid) so they render behind component boxes

- **Arrowheads:** Defined via SVG markers

- **Security Flows:** Use dashed lines in rose color (`#fb7185`)

- **Boundaries:**

- *Security Groups:* Dashed (`4,4`), rose color

- *Regions:* Large dashed (`8,4`), amber color, `rx="12"`

### Spacing & Layout Logic

- **Standard Height:** 60px (Services); 80-120px (Large components)

- **Vertical Gap:** Minimum 40px between components

- **Message Buses:** Must be placed *in the gap* between services, not overlapping them

- **Legend Placement:** **CRITICAL.** Must be placed outside all boundary boxes. Calculate the lowest Y-coordinate of all boundaries and place the legend at least 20px below it.

## Document Structure

The generated HTML file follows a four-part layout:

1. **Header:** Title with a pulsing dot indicator and subtitle

2. **Main SVG:** The diagram contained within a rounded border card

3. **Summary Cards:** A grid of three cards below the diagram for high-level details

4. **Footer:** Minimal metadata

### Info Card Pattern

```html

<h3>Title</h3>

</div>

<ul>

</ul>

</div>

```

## Output Requirements

- **Single File:** One self-contained `.html` file

- **No External Dependencies:** All CSS and SVG must be inline (except Google Fonts)

- **No JavaScript:** Use pure CSS for any animations (like pulsing dots)

- **Compatibility:** Must render correctly in any modern web browser

## Template Reference

Load the full HTML template for the exact structure, CSS, and SVG component examples:

```

skill_view(name="architecture-diagram", file_path="templates/template.html")

```

The template contains working examples of every component type (frontend, backend, database, cloud, security), arrow styles (standard, dashed, curved), security groups, region boundaries, and the legend — use it as your structural reference when generating diagrams.