arch-diagram

System Architecture Diagram Generator

Create polished system architecture diagrams in a clean tech infographic style using a two-step process: Mermaid mental model first, then image generation via the Gemini REST API.

Model: gemini-3-pro-image-preview (Nano Banana Pro) — highest quality, uses Thinking to refine composition before rendering.

Process

Step 1: Mermaid Mental Model

Before generating any image, write a Mermaid diagram that captures the system's components, data flow, and numbered steps. Present this inline, then immediately proceed to Step 2 without waiting for approval.

Example:

graph TD
    A[Flutter App] -->|1. Auth request| B[AWS Cognito]
    B -->|2. JWT token| A
    A -->|3. API call + JWT| C[API Gateway]
    C -->|4. Validate JWT| B
    C -->|5. Route request| D[Lambda Functions]
    D -->|6. Query| E[RDS Proxy]
    E -->|7. SQL| F[(PostgreSQL)]

Step 2: Generate Image via REST API

Build the prompt per the template below, then invoke the bundled generator script:

"${CLAUDE_PLUGIN_ROOT}/skills/arch-diagram/scripts/generate.sh" \
  --aspect-ratio "16:9" \
  --size "2K" \
  "<full prompt text>"

Options (ask the user if they have a preference, otherwise use defaults):

Flag	Default	Options
--aspect-ratio	16:9	1:1 4:3 3:2 16:9 21:9 3:4 2:3 9:16
--size	2K	1K 2K 4K

The script resolves GEMINI_API_KEY, POSTs to gemini-3-pro-image-preview:generateContent, writes the PNG to ./arch-diagram/, and prints the output path. It automatically skips intermediate Thinking images and saves only the final rendered output.

tech infographic Visual Style (include verbatim in every prompt)

Always append this exact style block to the image generation prompt:

Draw this as a polished tech infographic-style system architecture infographic on a clean white background.

Icons & Logos — most important rule: For every well-known service or platform (AWS Lambda, S3, DynamoDB, API Gateway, Cognito, SQS, SNS, Kubernetes, Docker, GitHub, YouTube, TikTok, Stripe, Twilio, Kafka, Redis, PostgreSQL, MongoDB, Nginx, Cloudflare, Vercel, etc.), render its real, recognizable logo or brand mark inside the component box. Do not use generic shapes for services that have an official logo. The logos should be clean, flat, and correctly colored.

Colors — use brand-accurate colors for known services:

• AWS services: AWS orange (#FF9900) accent, light orange background
• Google Cloud: Google blue (#4285F4) accent
• Azure: Microsoft blue (#0078D4) accent
• YouTube: red (#FF0000) accent
• TikTok: black (#010101) with pink (#EE1D52) accent
• Stripe: purple (#635BFF) accent
• GitHub: dark (#24292E) accent
• Kafka: black accent
• Redis: red (#DC382D) accent
• PostgreSQL: blue (#336791) accent
• MongoDB: green (#47A248) accent For custom or unknown services, use a clean pastel: light blue, light purple, light orange, light green, or light gray.

Layout & Structure:

• Arrange components in a clear left-to-right or top-to-bottom flow
• Group related services inside lightly shaded rounded rectangles with a subtle colored border (e.g., "AWS Cloud", "Client Layer")
• For comparisons (A vs B), use two clear vertical columns side by side with a thin divider
• Use generous whitespace between groups

Component boxes:

• Rounded rectangles with a colored left-border accent (using the service's brand color)
• Logo/icon on the left, bold service name on the right, 14px sans-serif
• Subtle drop shadow (2px, 10% opacity)

Connections:

• Solid thin arrows (#333333) for synchronous calls
• Dashed thin arrows (#999999) for async / event-driven calls
• Each arrow labeled with a circled step number ①②③… and a short action verb
• Labels in 11px gray sans-serif, mid-arrow

Typography:

• Bold sans-serif title at the top, 22px, dark charcoal (#1A1A2E)
• Thin green or brand-colored accent bar on the left of the title
• Section/group labels in 11px ALL-CAPS gray

Polish:

• No 3D effects, no gradients, no decorative borders
• High resolution, clean, educational — looks like a real tech infographic blog post diagram

Prompt Construction

Combine these four parts in order:

1. Title line: System architecture diagram titled '[Title]'.
2. Components: One bullet per service — name, what logo/icon to use, which group it belongs to
3. Flow: One bullet per numbered step — source → action → destination
4. Style block: The full tech infographic style description above (verbatim)

Template:

System architecture diagram titled '[TITLE]'.

Components:
- [Service Name]: use its real logo, in [Group] (e.g., 'AWS Lambda: use real AWS Lambda logo, in AWS Cloud')
- [Service Name]: use its real logo, in [Group]
- [Custom Service]: [describe icon], in [Group]
...

Flow:
- ① [Source] sends [action] to [Destination]
- ② [Destination] returns [response] to [Source]
...

[STYLE BLOCK — paste verbatim]

For comparison diagrams (A vs B), use this layout hint instead:

System architecture diagram titled '[Title: A vs B]'.
Two-column layout: left column for [A], right column for [B], with a thin vertical divider.

Left column — [A]:
- [services...]

Right column — [B]:
- [services...]

[STYLE BLOCK — paste verbatim]

After Generation

1. List ./arch-diagram/ to find the generated file
2. Show the image to the user via the Read tool
3. Ask if they want changes — common refinements:
   • "Add/remove a component"
   • "Change the flow direction"
   • "Make the logos larger / more prominent"
   • "Change to 4:3 or 1:1 aspect ratio"
   • "Regenerate at 4K for print quality"
4. For edits, update the Mermaid model first, then regenerate

Tips

• Keep diagrams to 5–10 components max per column/section for readability
• Use at most 8–10 numbered steps
• Always explicitly say "use its real logo" for known services — this is the biggest quality lever
• Use --size 4K for high-fidelity exports; --size 1K for quick iteration