architecture-diagram

name	architecture-diagram
description	Generate self-contained HTML architecture diagrams (inline SVG, dark theme, no JS) for blogs/READMEs. Triggers on system architecture, microservices, cloud/AWS/GCP, K8s, network topology, data flow diagrams. Use `drawio` instead when the output needs to be editable.
argument-hint	[system description or .md path] [--output path.html]
allowed-tools	Read, Write, Bash
author	Cocoon AI (adapted by Maki)
version	1.1.0
tags	["diagram","architecture","svg","html","blog","documentation"]
required_env	[]
required_bins	[]
platforms	["macos","linux","windows"]
safety_level	safe
credits	{"upstream":"github.com/Cocoon-AI/architecture-diagram-generator (MIT)","enriched":"semantic vocabulary + brand colors + AI patterns from fireworks-tech-graph (MIT)"}

Architecture Diagram Skill

Create professional technical architecture diagrams as self-contained HTML files with inline SVG graphics and CSS styling.

Philosophy

• Shape encodes meaning: LLM = double-border rect, Agent = hexagon, Vector Store = ringed cylinder, Memory = dashed rect. Readers decode architecture at a glance.
• Arrow color/dash encodes semantics: sync vs async vs auth vs data-read vs data-write vs control-loop use different strokes and markers.
• Dark theme only: one style, done well. Keeps decisions fast.

Reference Files

Load these when the diagram involves AI/Agent systems or needs product branding:

• references/semantic-shapes.md — LLM / Agent / Vector Store / Memory / Tool / Queue / User shapes with ready-to-paste SVG + dark palette
• references/brand-colors.json — 40+ product brand colors (OpenAI, Anthropic, Pinecone, Kafka, etc.) for inline badges
• references/ai-patterns.md — RAG / Mem0 / Multi-Agent / Tool Call / Agentic Search swim-lane presets

Design System

Color Palette

Use these semantic colors for component types:

Component Type	Fill (rgba)	Stroke
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/Generic	rgba(30, 41, 59, 0.5)	#94a3b8 (slate-400)

Typography

Use JetBrains Mono for all text (monospace, technical aesthetic):

<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">

Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels.

Visual Elements

Background: #020617 (slate-950) with subtle grid pattern:

<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
  <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>

Component boxes: Rounded rectangles (rx="6") with 1.5px stroke, semi-transparent fills.

Security groups: Dashed stroke (stroke-dasharray="4,4"), transparent fill, rose color.

Region boundaries: Larger dashed stroke (stroke-dasharray="8,4"), amber color, rx="12".

Arrows: Use SVG marker for arrowheads:

<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
  <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
</marker>

Arrow z-order: Draw connection arrows early in the SVG (after the background grid) so they render behind component boxes. SVG elements are painted in document order, so arrows drawn first will appear behind shapes drawn later.

Masking arrows behind transparent fills: Since component boxes use semi-transparent fills (rgba(..., 0.4)), arrows behind them will show through. To fully mask arrows, draw an opaque background rect (e.g., fill="#0f172a") at the same position before drawing the semi-transparent styled rect on top:

<!-- Opaque background to mask arrows -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#0f172a"/>
<!-- Styled component on top -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>

Auth/security flows: Dashed lines in rose color (#fb7185).

Message buses / Event buses: Small connector elements between services. Use orange color (#fb923c stroke, rgba(251, 146, 60, 0.3) fill):

<rect x="X" y="Y" width="120" height="20" rx="4" fill="rgba(251, 146, 60, 0.3)" stroke="#fb923c" stroke-width="1"/>
<text x="CENTER_X" y="Y+14" fill="#fb923c" font-size="7" text-anchor="middle">Kafka / RabbitMQ</text>

Spacing Rules

CRITICAL: When stacking components vertically, ensure proper spacing to avoid overlaps:

• Standard component height: 60px for services, 80-120px for larger components
• Minimum vertical gap between components: 40px
• Inline connectors (message buses): Place IN the gap between components, not overlapping

Example vertical layout:

Component A: y=70,  height=60  → ends at y=130
Gap:         y=130 to y=170   → 40px gap, place bus at y=140 (20px tall)
Component B: y=170, height=60  → ends at y=230

Wrong: Placing a message bus at y=160 when Component B starts at y=170 (causes overlap) Right: Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170)

Legend Placement

CRITICAL: Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups).

• Calculate where all boundaries end (y position + height)
• Place legend at least 20px below the lowest boundary
• Expand SVG viewBox height if needed to accommodate

Example:

Kubernetes Cluster: y=30, height=460 → ends at y=490
Legend should start at: y=510 or below
SVG viewBox height: at least 560 to fit legend

Wrong: Legend at y=470 inside a cluster boundary that ends at y=490 Right: Legend at y=510, below the cluster boundary, with viewBox height extended

Layout Structure

1. Header - Title with pulsing dot indicator, subtitle
2. Main SVG diagram - Contained in rounded border card
3. Summary cards - Grid of 3 cards below diagram with key details
4. Footer - Minimal metadata line

Component Box Pattern

<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
<text x="CENTER_X" y="Y+20" fill="white" font-size="11" font-weight="600" text-anchor="middle">LABEL</text>
<text x="CENTER_X" y="Y+36" fill="#94a3b8" font-size="9" text-anchor="middle">sublabel</text>

Info Card Pattern

<div class="card">
  <div class="card-header">
    <div class="card-dot COLOR"></div>
    <h3>Title</h3>
  </div>
  <ul>
    <li>• Item one</li>
    <li>• Item two</li>
  </ul>
</div>

Template

Copy and customize the template at assets/template.html. Key customization points:

1. Update the <title> and header text
2. Modify SVG viewBox dimensions if needed (default: 1000 x 680)
3. Add/remove/reposition component boxes
4. Draw connection arrows between components
5. Update the three summary cards
6. Update footer metadata

Output

Always produce a single self-contained .html file with:

• Embedded CSS (no external stylesheets except Google Fonts)
• Inline SVG (no external images)
• No JavaScript required (pure CSS animations)

The file should render correctly when opened directly in any modern browser.