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
- Parse user input → extract: components (with descriptions), containment hierarchy (zones/nesting), connections (with semantic types), and any provider context
- Read
references/icons.md— select or create icons for each component - Read
references/layout-patterns.md— choose topology pattern, set grid-template-columns - Read
references/connections.md— define connection array with types, side-forcing, routing - Start from
assets/template.html— use its CSS/JS structure as the base - 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
- Output final
.htmlto the working directory or user-specified path
Node construction
Every node must have:
- Unique
data-node-id(semantic:fusion-hcm,edi-adaptor, notnode-7) .node-iconwith 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.zonehas exactly onespan.zone-labeland onediv.zone-content - Every
div.zone-contenthas explicitstyle="grid-template-columns:..." - Zone depth class (
zone-depth-0tozone-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 databatch(red dashed): SFTP, file transfers, EDI, scheduled batch jobs, bulk dataevent(green solid): event-driven triggers, pub-sub, webhooks, callbacks, business eventscontrol(orange dashed): management plane, monitoring, config push, admin flowsdefault(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
defaultconnections 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 |
| Zone nesting exceeds depth-3 styling | Architecture has more than 4 containment levels | Flatten by combining the deepest two levels into a single zone, or split into two separate diagrams linked by description |
References
references/icons.md— 28+ SVG icon definitions, custom icon rules, provider color tablereferences/layout-patterns.md— node structure, zone nesting, 5 topology patterns, interior grid guidance, sizing tablereferences/connections.md— connection schema, 6 semantic types with colors, side-forcing, route modes, legend markupassets/template.html— complete HTML skeleton: CSS, legend, zone/node styles, marker defs for all colors, connection renderer JS with auto side-detection