mermaid-diagrams

Mermaid Diagrams

Text-first diagramming for architecture documents, specs, and READMEs. Mermaid renders natively in GitHub, GitLab, and most Markdown viewers; sources live in the repo and diff cleanly.

Mermaid vs draw.io (see also the diagramming-conventions steering file): use Mermaid for logical views (C4, sequence, state, flows) embedded in Markdown; use the drawio-aws/drawio-azure/drawio-gcp skills when the audience expects official cloud provider icons or a standalone .drawio artifact.

Validation

Every diagram must compile before it ships:

npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o /tmp/diagram.svg

Exit code 0 = valid. For diagrams embedded in Markdown, extract the fenced block to a temp .mmd file first. Render PNG for decks/docs with -o out.png -s 3.

C4 Model (levels 1–3)

Mermaid has first-class C4 syntax. Keep one level per diagram (see the c4-model steering file for when to use each level).

Level 1 — System Context

C4Context
  title System Context — Order Platform
  Person(customer, "Customer", "Places orders via web/mobile")
  System(orders, "Order Platform", "Accepts, prices, and fulfils orders")
  System_Ext(payments, "Payment Gateway", "Card authorisation")
  System_Ext(email, "Email Provider", "Transactional email")
  Rel(customer, orders, "Browses, orders", "HTTPS")
  Rel(orders, payments, "Authorises payment", "HTTPS/REST")
  Rel(orders, email, "Sends confirmations", "SMTP/API")

Level 2 — Container

C4Container
  title Container View — Order Platform
  Person(customer, "Customer")
  System_Boundary(plat, "Order Platform") {
    Container(web, "Web App", "React", "Customer-facing storefront")
    Container(api, "Order API", "Node.js/Fastify", "Order lifecycle endpoints")
    Container(worker, "Fulfilment Worker", "Node.js", "Consumes order events")
    ContainerDb(db, "Order DB", "PostgreSQL", "Orders, customers, payments")
    ContainerQueue(bus, "Event Bus", "EventBridge", "OrderPlaced, OrderShipped")
  }
  Rel(customer, web, "Uses", "HTTPS")
  Rel(web, api, "Calls", "JSON/HTTPS")
  Rel(api, db, "Reads/writes", "SQL")
  Rel(api, bus, "Publishes events")
  Rel(bus, worker, "Delivers events")