/architecture-diagram

name: architecture-diagram
description: 'Generate layered architecture diagrams as self-contained HTML with inline SVG icons, CSS Grid containers, and connection overlays. Triggers on: "architecture diagram", "infra diagram", "system diagram", "deployment diagram", "topology", "draw architecture". NOT for architecture reviews, use architecture-reviewer.'
metadata:
  version: 1.1.1
  category: review
  tags: [architecture, diagram, visualization, svg]
  difficulty: intermediate

Architecture Diagram Generator

Produces self-contained `.html` files: inline SVG icons, CSS Grid nested zones, JS-driven SVG connection overlay with color-coded semantic line types and arrowhead markers. Zero external dependencies.

Workflow

1. **Parse** user input → extract: components (with descriptions), containment hierarchy (zones/nesting), connections (with semantic types), and any provider context 2. **Read** `references/icons.md` — select or create icons for each component 3. **Read** `references/layout-patterns.md` — choose topology pattern, set grid-template-columns 4. **Read** `references/connections.md` — define connection array with types, side-forcing, routing 5. **Start from** `assets/template.html` — use its CSS/JS structure as the base 6. **Assemble** the HTML:

• Set `{{DIAGRAM_TITLE}}`, `{{BG_COLOR}}`, `{{MAX_WIDTH}}`
• Populate `{{LEGEND_ITEMS}}` — one entry per connection type used
• Build zone hierarchy as nested `div.zone > span.zone-label + div.zone-content`
• Place nodes with `data-node-id`, each containing: `.node-icon` (inline SVG), `.node-title`, `.node-desc`
• Populate the `connections` JS array
• Apply provider theming if applicable

7. **Output** final `.html` to the working directory or user-specified path

Node construction

Every node must have:

• Unique `data-node-id` (semantic: `fusion-hcm`, `edi-adaptor`, not `node-7`)
• `.node-icon` with inline SVG from the icon registry (or custom-generated following registry constraints)
• `.node-title` — short name (1–3 words, bold)
• `.node-desc` — extended description text (protocols, module lists, capabilities). Populate this whenever the user provides detail beyond just a name. This is critical for professional-quality diagrams.

Key structural invariants

• Every `div.zone` has exactly one `span.zone-label` and one `div.zone-content`
• Every `div.zone-content` has explicit `style="grid-template-columns: ..."`
• Zone depth class (`zone-depth-0` to `zone-depth-3`) matches actual nesting level
• All SVG icons are inline inside `.node-icon` — no external image references
• Connection overlay SVG with `<defs>` (arrow markers for each color) sits after the diagram div
• Connection renderer `<script>` is last before `</body>`
• Legend div sits above the diagram div, containing only types actually used

Connection type selection

Match connection semantics to the appropriate type:

• **`realtime`** (blue solid): REST, SOAP, API calls, synchronous requests, real-time data
• **`batch`** (red dashed): SFTP, file transfers, EDI, scheduled batch jobs, bulk data
• **`event`** (green solid): event-driven triggers, pub-sub, webhooks, callbacks, business events
• **`control`** (orange dashed): management plane, monitoring, config push, admin flows
• **`default`** (blue solid): when semantic type is ambiguous or only one flow type exists

When the user doesn't specify flow semantics, default all connections to `default` type and omit the legend.

Design defaults

• Background: `#f0ece4` (warm neutral) or `#e8eef5` (cool blue-gray) — choose based on provider/context
• Zone borders: dashed, colored by depth (warm browns → reds)
• Icons: 44×44px, `--icon-color: #3a3a3a` (or provider-specific)
• Node title: 12px bold, node desc: 10.5px regular #555
• Connections: 2px stroke, curved by default
• Font: Segoe UI / system-ui stack
• Max-width: 1400px typical, increase for complex diagrams

Handling ambiguity

• Infer zone nesting from naming conventions (Region > VPC > Subnet, etc.)
• Default to `default` connections and no legend if flow types are unspecified
• Place management/observability services outside the main data-path zones
• Use generic icon set and warm-neutral background unless provider is specified
• Ask for clarification only when component list or topology is fundamentally ambiguous

Error Handling

| Problem | Cause | Fix | | ----------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assets/template.html` missing | File deleted or skill directory incomplete | Regenerate from skill defaults: reconstruct the CSS/JS skeleton using the structure documented in this SKILL.md and the reference files | | Icon reference not found in `references/icons.md` | Component type not in the registry | Fall back to the generic box icon defined in `references/icons.md § Generic Fallback`; log the missing icon name in a comment | | Connection lines overlap or route through nodes | Dense graph with auto-routing conflicts | Adjust zone layout: increase `grid-template-columns` spacing, add intermediate waypoint nodes, or use `side-forcing` attributes from `references/connections.md` | | Playwright render failure during HTML-to-image export | Chromium not installed or script error | Run `playwright install chromium`; check browser console via `--headed` flag; verify no JS syntax errors in the connection renderer script | |