An architecture diagram in Mermaid is text, so it lives in the repository next to the system it describes and updates in the same pull request. Copy one of the patterns below, edit the names, and export a PNG or SVG for your docs.
No signup · No watermark · Renders in your browser · PNG, SVG, JPG, WebP, PDF
Architecture diagrams tend to answer one of three questions: what talks to what, what happens during one request, or what runs where. Each needs a different Mermaid grammar.
What talks to what. Group services into boundaries with subgraph, and give data stores the cylinder shape so storage is readable at a glance.
flowchart LR
subgraph edge["Edge"]
cdn["CDN"]
end
subgraph app["Application"]
api["API"]
worker["Worker"]
end
cdn --> api
api --> db[("Postgres")]
api --> queue[("Queue")]
queue --> worker
worker --> dbWhat happens during one request, in order. A sequence diagram shows timing and return values, which a topology diagram cannot.
sequenceDiagram
participant Client
participant API
participant Cache
participant DB
Client->>API: GET /orders
API->>Cache: read
Cache-->>API: miss
API->>DB: SELECT
DB-->>API: rows
API-->>Client: 200 JSONWhat runs where. Use subgraph for each environment or cluster, and dotted arrows for anything that crosses a trust boundary.
flowchart TB
subgraph cluster["Kubernetes"]
ingress["Ingress"]
pods["App pods"]
end
subgraph managed["Managed"]
rds[("RDS")]
end
users(["Users"]) --> ingress
ingress --> pods
pods --> rds
pods -.-> logs["Log sink"]The starter below is a small service topology. Change the names, pick an export style, and download a PNG or SVG — everything renders locally in your browser.
Export controls activate after your diagram renders locally.
Use a flowchart when the question is what connects to what — services, stores, and boundaries. Use a sequence diagram when the question is what happens in what order during a single request, including responses and timeouts. Many systems need both, and they are cheap to keep side by side because each is only a few lines of text.
Wrap the nodes in a subgraph and give it a quoted label: subgraph vpc["Production VPC"]. Subgraphs nest, so you can put a cluster inside an account inside a region, though more than two levels usually means the diagram is trying to say too much at once.
Around a dozen nodes is the practical ceiling for a diagram someone reads in a document. Past that, split it: one overview where each boundary is a single node, plus a detail diagram per boundary. That is easier to keep accurate than one large canvas, because each diagram changes with the code it describes.
Recent Mermaid versions include an architecture-beta grammar with cloud icons, but it is still changing between releases and renders inconsistently across platforms. A plain flowchart with subgraphs and shape conventions is portable, renders the same in GitHub and in this tool, and will not break when the grammar moves.
SVG when the destination renders it — text stays selectable and the diagram scales cleanly. PNG at 2x when the destination is a slide deck, an issue tracker, or any platform that strips SVG. Both export without a watermark here.