Architecture diagram

Architecture Diagram

End-to-end architecture diagram generation. Gathers system information, produces an HTML file, renders it to PNG via Chrome headless, and delivers the final image. The entire export is automated -- the user never needs to open a browser or run a script manually.

Two visual styles: dark theme (default, SVG-based) and light theme (div-based, print-friendly).

Workflow

Step 1: Gather information

Before writing markup, identify from the request (ask clarifying questions if anything is ambiguous):

• Components: servers, services, databases, queues, external systems
• Data flow: direction of requests (top-down, left-to-right, mixed)
• Groupings: which components belong together (VPC, cluster, tier)
• Boundary types: cloud regions, security groups, Kubernetes namespaces
• Theme: dark (default) or light (for print/slides/white-background docs)
• Output path: where to save the final PNG (default: tmp/ in the project directory)

When the request references a blog post or design document, read it and extract component names and relationships before writing markup.

Ask the user for clarification only when the system description is genuinely ambiguous. Do not ask questions that can be reasonably inferred.

Step 2: Select style and start the file

Dark theme (default): Copy resources/template.html as the starting point. Includes inline SVG, CSS, grid background, arrowhead marker, export toolbar stub, and example component patterns.

Light theme: Build from the patterns in references/diagram-styles.md. Div-based layout with CSS classes (.node .service, .db, .group), Inter font, white #FFFFFF background.

For either style, do not start from a blank file. Save the working HTML to tmp/ with a descriptive filename (e.g., tmp/my-project-architecture.html).

Step 3: Place components

Dark theme: SVG <rect> + <text> pairs.

Light theme: div elements with category CSS classes.

Assign colors by semantic type:

Type	Dark Stroke	Light Class	Use For
Frontend	#22d3ee (cyan)	.service	Web apps, mobile clients, SPAs
Backend	#34d399 (emerald)	.server	API servers, microservices, workers
Database	#a78bfa (violet)	.storage	SQL, NoSQL, caches, object stores
Cloud	#fbbf24 (amber)	.infra	AWS/GCP/Azure managed services
Security	#fb7185 (rose)	.external	Auth providers, WAFs, IAM
Message Bus	#fb923c (orange)	.storage	Kafka, RabbitMQ, SQS, event buses
External	#94a3b8 (slate)	.external	Third-party APIs, CDN, SaaS

For exact fill values, SVG code snippets, and light-theme CSS, consult:

• Dark theme: references/design-system.md
• Light theme: references/diagram-styles.md

Step 4: Draw boundaries

• Cloud regions / VPCs: dashed rect (stroke-dasharray="8,4"), amber, rx="12"
• Security groups: dashed rect (stroke-dasharray="4,4"), rose, transparent fill
• Kubernetes namespaces: dashed rect, slate
• Light theme: .group class with dashed #bbb border

Place boundary labels at the top-left corner inside the boundary.

Step 5: Connect with arrows

Dark theme: SVG <line> or <path> with marker-end="url(#arrowhead)".

• Standard flow: solid lines, slate #64748b
• Auth/security: dashed (stroke-dasharray="5,5"), rose #fb7185

Light theme: CSS .arrow-down (shaft + triangle head) or .connector-h (Unicode arrows).

Z-order (dark theme): draw arrows after the background grid but before component boxes. SVG renders in document order. To mask arrows behind semi-transparent boxes, add an opaque <rect fill="#0f172a"> beneath the styled rect. Full pattern in references/design-system.md.

Step 6: Apply spacing rules

• Standard component height: 60px (services), 80-120px (larger)
• Minimum vertical gap: 40px
• Message bus connectors: place inside the gap, not overlapping boxes

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

Step 7: Add legend

Place the legend OUTSIDE all boundary boxes. Calculate the lowest boundary edge, start the legend at least 20px below it. Extend the SVG viewBox (dark) or body height (light) if needed.

Step 8: Render to PNG

After saving the HTML file, immediately render it to PNG using the screenshot script:

bash scripts/screenshot.sh tmp/diagram.html tmp/diagram.png

The script:

• Auto-detects canvas dimensions from the HTML body CSS (no need to pass width/height unless overriding)
• Requires google-chrome, google-chrome-stable, chromium-browser, or chromium in PATH
• On success, prints: saved: <path> (<width>x<height>)

Override dimensions when auto-detect fails or the diagram needs a specific size:

bash scripts/screenshot.sh tmp/diagram.html tmp/diagram.png 1200 900

This step is mandatory. Do not stop after writing the HTML. Always produce the PNG.

Step 9: Verify the output

Read the generated PNG file and check:

• All labels readable (no overlapping text)
• Arrows connect correct components
• Boundaries contain all intended children
• No content clipped by viewport edges
• Legend is outside all boundaries
• Summary cards reflect the diagram content

If issues are found, fix the HTML and re-run Step 8.

Step 10: Deliver

Report the exact file paths of both artifacts:

HTML: tmp/my-project-architecture.html
PNG:  tmp/my-project-architecture.png

The HTML file is the editable source. The PNG is the deliverable. Keep both unless the user asks to remove the HTML.

The dark-theme HTML also contains a browser-based export toolbar (Copy/PNG/PDF via html2canvas + jsPDF) for ad-hoc re-export. This is a convenience feature -- the primary export is always via scripts/screenshot.sh.

Canvas Sizes

Type	Dark (SVG viewBox)	Light (body px)
Standard	1000 x 680	1200 x 900
Wide	1200 x 680	1200 x 900
Tall	1000 x 900	1200 x 1200

Additional Resources

• resources/template.html -- Dark-theme template with all SVG patterns, CSS, grid background, and export toolbar. Copy to start every dark-theme diagram.
• examples/diagram-template.html -- Complete working example: three-tier web architecture with CDN, load balancer, API servers, cache, database, message bus, workers, and legend. Useful as a reference for layout and spacing.
• references/design-system.md -- Dark-theme design system: rgba fill values, typography scale, all SVG code patterns, boundary styles, legend pattern, export toolbar internals.
• references/diagram-styles.md -- Light-theme reference: CSS classes, node types, group boxes, database cylinder pattern, arrow styles, typography, canvas dimensions.
• scripts/screenshot.sh -- Chrome headless PNG capture. Auto-detects dimensions from HTML body CSS. Supports both themes.