Architecture Diagram

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 (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. If the user wants to view/share the diagram in chat (web console, WeCom / 企业微信, DingTalk, Feishu, Telegram, ...): call render_html_image(filePath="", filename="") 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

Delivering through chat / IM channels

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/ 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:

# 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

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

  
    
    Title
  
  
    • Item one
    • Item two
  

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mateaix
• Source: mateaix/mateclaw
• License: Apache-2.0
• Homepage: https://claw.mate.vip

Install and usage instructions live in the source repository linked above.