architecture-diagram

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture Diagram — Self-Contained HTML+SVG Diagrams

Create professional technical architecture diagrams as **single self-contained
HTML files** with inline SVG graphics and CSS styling. The output renders
correctly when opened directly in any modern browser — no build step, no
JavaScript framework, no external images.

## When to use

- System, infrastructure, cloud, security, or network-topology diagrams.
- A shareable, presentation-ready visual artifact is the deliverable.
- Dark-theme technical aesthetic is desired.

For methodology (what to draw at each level), pair with `architecture/c4-model`;
for lightweight in-repo text diagrams, use `tooling/mermaid`. This skill covers
the **rendered artifact** case.

## Workflow

1. Copy `resources/template.html` as the starting point.
2. Customize the `<title>`, header text, and footer metadata.
3. Adjust the SVG `viewBox` if needed (default `1000 x 680`).
4. Add/reposition component boxes using the component pattern below.
5. Draw connection arrows early in the SVG (after the background grid) so they
   render behind boxes.
6. Update the three summary cards and legend.
7. Deliver one `.html` file.

## Design system

### Semantic color palette

| Component type | Fill (rgba) | Stroke |
|----------------|-------------|--------|
| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` |
| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` |
| Database | `rgba(76, 29, 149, 0.4)` | `#a78bfa` |
| AWS/Cloud | `rgba(120, 53, 15, 0.3)` | `#fbbf24` |
| Security | `rgba(136, 19, 55, 0.4)` | `#fb7185` |
| Message bus | `rgba(251, 146, 60, 0.3)` | `#fb923c` |
| External/Generic | `rgba(30, 41, 59, 0.5)` | `#94a3b8` |

### Typography

JetBrains Mono throughout (monospace, technical aesthetic):

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

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

### Visual elements

**Background:** `#020617` with a subtle grid pattern:

```svg
<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"`), 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:** SVG marker arrowheads:

```svg
<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>
```

Draw arrows before boxes so they layer behind components.

**Masking arrows behind transparent fills:** semi-transparent box fills let
arrows show through. Pre-draw an opaque rect (`fill="#0f172a"`) beneath the
styled rect:

```svg
<!-- 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, rose color (`#fb7185`).

**Message/event buses:** small connectors placed in the vertical gap between
services:

```svg
<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>
```

### Component box pattern

```svg
<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

```html
<div class="card">
  <div class="card-header">
    <div class="card-dot COLOR"></div>
    <h3>Title</h3>
  </div>
  <ul>

From ulises-jeremias/agent-toolkit, MIT.