mermaid-diagram

name	mermaid-diagram
description	Generate Mermaid diagrams (flowchart, sequence, architecture, deployment, class, state, ER) from a description or source code, with high-contrast styling and syntax validation. Trigger on "create/generate a diagram", "document this architecture", "diagram this code/workflow", or a doc needing an embedded diagram.

Mermaid Diagram Generator

Pick the diagram type the request actually needs, generate valid Mermaid syntax with readable (high-contrast) styling, and validate before handing it back — a diagram that fails to render is worse than no diagram.

1. Pick the Diagram Type

Request sounds like	Diagram type	Mermaid syntax
Workflow, process, business logic, user flow, decision points	Activity/flowchart	flowchart TD (or LR)
API calls, service-to-service interaction, request/response order	Sequence	sequenceDiagram
System components, module boundaries, high-level structure	Architecture	flowchart TB with subgraphs, or architecture-beta
Infrastructure, cloud resources, network topology, k8s	Deployment	flowchart TB with subgraphs per environment/zone
Class/type relationships, OOP structure	Class	classDiagram
Finite states and transitions	State	stateDiagram-v2
Entity relationships, schema	ER	erDiagram
Timeline, project schedule	Gantt	gantt

When code is provided instead of a description, read it first — for architecture, follow the layer boundaries (controller/service/repository, component tree, pipeline stages) already in the code rather than inventing new groupings; for sequence, follow the actual call order.

Full syntax reference and a worked example per type is in references/details.md — read the section for the chosen type before writing the diagram body.

2. Style for Readability

• Every classDef sets an explicit color:. Mermaid's default theme text color doesn't always contrast against a custom fill: — a light fill needs a dark color:, a dark fill needs a light one. This is the single most common "the diagram renders but you can't read half of it" bug.
• One diagram, one concept. If a request needs both "how the request flows" and "what infrastructure it runs on," that's a sequence diagram and a deployment diagram, not one diagram trying to be both.
• Label edges when the label carries information (-->|"validates"|), skip it when the arrow direction alone says everything.

Size and Complexity Guardrail

A diagram exists so someone can understand a system faster than reading the code or the prose — one that needs to be scrolled, zoomed, or squinted at has stopped doing that job. Fit it on a single screen at a readable size:

• ~15-20 nodes is the practical ceiling for a flowchart, sequence, or architecture diagram before it stops being scannable in one glance. If the real system genuinely has more moving parts than that, that's a sign the request wants several diagrams at different zoom levels (one overview + one detail diagram per subsystem), not one diagram trying to hold all of it.
• Collapse repetition. Three near-identical worker nodes doing the same job become one node labeled Worker (×3), not three copies cluttering the canvas — detail that doesn't change the reader's understanding of the system isn't worth the space it takes.
• Prune to the concept being explained. A deployment diagram answering "where does this run" doesn't need every IAM policy and env var — only the parts that inform that question. Leaving out accurate-but-irrelevant detail is not the same as leaving out something that would change the reader's understanding.
• If it still doesn't fit, split it — an overview diagram with subgraphs collapsed to single boxes, linked to a separate detail diagram per subgraph, beats one dense diagram nobody can parse. Say so rather than forcing everything onto one canvas.

Which Emoji for Which Node

Unicode symbols exist to mark node kind at a glance, not to decorate — a reader should be able to tell "that's a datastore" or "that's external" from the icon alone, before reading the label. Pick from the fixed vocabulary below and use each symbol for the same kind of node everywhere in the diagram; skip symbols entirely on a dense diagram where they'd just add clutter, rather than using them inconsistently.

Kind	Symbol	Use for
Actor / user	👤	End user, external human actor
Client / frontend	🖥️ / 📱	Web app, mobile app, browser
Gateway / edge	🌐	API gateway, load balancer, CDN, ingress
Compute	⚙️	App server, service, worker, function/lambda
Async job	🔄	Background job, scheduled task, retry loop
Relational DB	💾	Postgres, MySQL, RDS — durable structured storage
Cache	⚡	Redis, Memcached, in-memory store
Object storage	📦	S3, GCS, blob storage, file store
Queue / message bus	📬	Kafka, SQS, RabbitMQ, pub/sub topic
Auth / security	🔐	Auth service, IAM, secrets manager, token issuer
External / third-party	☁️	Any service outside the system boundary — payment processor, external API
Network boundary	🌍	Internet, public network edge
Monitoring / logging	📊	Metrics, dashboards, log aggregation
Alert / failure state	⚠️ / ❌	Error path, failure branch, alert
Success / terminal state	✅	Completed, confirmed, terminal success node
Payment / billing	💳	Charge, invoice, billing step (activity diagrams)
Notification	📧 / 📬	Email, push notification, webhook fired

If a node doesn't clearly fit one of these categories, leave it unlabeled rather than reaching for an unrelated emoji — a wrong or generic symbol is worse than no symbol, because the reader will try to make it mean something.

3. Validate Before Handing It Back

Never present a diagram you haven't checked will actually render. If the Mermaid CLI is available:

npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -b transparent

A non-zero exit or stderr output means a syntax error — fix it before showing the result, don't ask the user to debug rendering. If mmdc isn't available (no npm/network), at minimum re-read the generated syntax against references/details.md's gotchas section (reserved words, arrow syntax, unescaped special characters) — these account for most Mermaid parse failures.

4. Output

Default to a fenced ```mermaid code block inline in the response or target markdown file — that's what renders directly in GitHub, most editors, and Claude's own UI. Only produce a standalone .mmd file (and PNG/SVG via mmdc -i in.mmd -o out.png) when the user is embedding the diagram somewhere that needs a static image, e.g. Confluence, a slide deck, or a doc format that doesn't render Mermaid natively.