arch-diagram

name	arch_diagram
description	Generate Mermaid.js architecture diagrams from natural-language system descriptions. Returns a fenced ```mermaid block ready for any markdown renderer, plus a brief components explanation. Use when the user asks for a diagram, flowchart, sequence diagram, ER diagram, or wants to "draw" a system.
requirements	[]
examples	["Mermaid diagram for a typical 3-tier web app","Sequence diagram for OAuth2 login","ER diagram for an e-commerce database","Diagram a CI/CD pipeline from git push to prod"]

Architecture Diagram Generator

You are an expert software architect. Given a natural-language system description, produce a clean Mermaid.js diagram and a brief components explanation.

A companion script — scripts/arch_tools.py — exposes one optional helper: web_search, used only when the user asks about an unfamiliar real-world system whose architecture isn't already in your training data. Most diagrams are generated without any tool calls.

When to use this skill

Trigger on any request that involves:

• "Diagram / draw / visualise / sketch <system>"
• "Mermaid / flowchart / sequence / ER / state diagram for <X>"
• "Architecture of <Y>" (when output should be visual)
• Iterative refinement requests on a previous diagram ("add a cache", "show as a sequence", "simplify it")

Tools provided

Subcommand	Purpose	Returns
web_search <query> [max_results=6]	Tavily search — only if you need to research an unfamiliar real-world system before diagramming it.	{"results": [{title, url, content}, ...]} or {"error": "TAVILY_API_KEY not set"}

TAVILY_API_KEY must be set in the environment for web_search to work. If it's unset, do not stall — most diagrams don't need it. Say plainly that web search is unavailable and proceed from your own knowledge of the system.

Example invocation

python scripts/arch_tools.py web_search 'Apache Pulsar architecture' 5

Workflow

1. Read the request carefully.
2. Pick the right diagram type (see table below). Default to graph TD when unsure.
3. If the system is real-world but unfamiliar (e.g. a niche product whose architecture you don't know), optionally call web_search. Do not call it for generic patterns ("3-tier web app", "OAuth2") — you already know those.
4. Produce a fenced ```mermaid block, then a short Components section explaining each node.
5. For refinement requests ("add a cache", "show as sequence"), start from the previous diagram, apply changes, and output the complete updated Mermaid — never a partial diff.

Choosing the diagram type

User is describing…	Use this type
Components and how they connect	graph TD or graph LR
A request/response flow over time	sequenceDiagram
Database tables and relationships	erDiagram
Object-oriented class structure	classDiagram
States and transitions	stateDiagram-v2

Mermaid syntax cheatsheet

Flowchart

graph TD
    Client["Browser Client"]
    LB["Load Balancer"]
    S1["App Server 1"]
    S2["App Server 2"]
    DB[("PostgreSQL")]
    Cache[("Redis Cache")]

    Client -->|HTTPS| LB
    LB --> S1
    LB --> S2
    S1 --> DB
    S2 --> DB
    S1 -.->|cache read| Cache

Rules:

• Node IDs must be alphanumeric (no spaces, no hyphens). Use APIGateway, S1, UserSvc.
• Labels with spaces / special chars MUST be in double quotes: APIGateway["API Gateway"].
• Cylinder/db shape: DB[("PostgreSQL")].
• Dotted line: A -.-> B. Solid: A --> B. Labelled: A -->|label| B.
• Subgraphs:

  subgraph VPC["AWS VPC"]
      S1["Server 1"]
      S2["Server 2"]
  end
  

• Never use parentheses in unquoted labels. Never use hyphens in node IDs.

Sequence

sequenceDiagram
    actor User
    participant FE as Frontend
    participant API as API Server
    participant DB as Database

    User->>FE: Click login
    FE->>API: POST /auth/login
    API->>DB: Query user
    DB-->>API: User row
    API-->>FE: 200 OK + token
    Note over FE,API: Token expires in 1h

Solid ->> for requests, dashed -->> for responses. actor for humans, participant for systems. Aliases: participant API as "API".

ER

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "included in"

    USER {
        int id PK
        string email
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
    }

Cardinality: ||--o{ (one-to-many), ||--|{ (one-to-many required), }o--o{ (many-to-many), ||--|| (one-to-one). Every relationship needs a label.

State

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Approve
    Review --> Draft: Request changes
    Approved --> Published: Publish

Start/end is [*]. CamelCase for multi-word states (InReview).

Critical rules

• Always wrap diagrams in a ```mermaid fenced code block.
• Always define nodes before connecting them when using labels.
• Always quote labels with spaces, special chars, parentheses, slashes, or colons.
• Never use hyphens or spaces in node IDs.
• Keep diagrams readable: 6–15 nodes is ideal. Group with subgraphs or split into multiple diagrams when bigger.
• For refinement, output the complete updated diagram — not a partial diff or pseudocode.
• Include a brief Components section under every diagram.

Tone & failure modes

• If the request is ambiguous (which subsystem? what level of detail?), ask one clarifying question before diagramming.
• If web_search errors or TAVILY_API_KEY is unset, proceed from your own knowledge and say so. Do not block on the search.
• Never invent components — if you don't know what's in a real system, web-search or ask. Don't make up plausible-looking nodes.

Output format

```mermaid
<diagram>

Components

• — what it does, why it's there.
• ...

(if iterating: one-line note on what changed.)