Microservices architecture
Gateway, services, databases, and an async message queue.
Every microservices system eventually needs the one diagram that answers "what talks to what?" — for new hires, for security reviews, for the architect deciding where the next service fits. This template is that diagram: users hit a load balancer, the API gateway fans out to auth, orders, and payments services grouped in a subgraph, each service owns its own data store, and an async message queue carries order events to a notification service that calls the email provider.
The shapes do real work here. Cylinders mark databases, double brackets mark the queue, and the subgraph draws the service boundary — so a reader can tell synchronous request paths from async event flow at a glance.
When to use this template
- System onboarding — give new engineers the whole topology in one view before they read a single line of service code.
- Architecture and security reviews — trace every path from the public internet to a database, and confirm that no service reaches into another service's data store.
- Planning new services — sketch where a new component plugs in (behind the gateway? consuming the queue?) before writing the design doc.
How to adapt it
Rename the services to your real domain, then layer in your infrastructure:
- Add service-to-service calls, such as Orders calling Payments synchronously, to expose coupling that reviews should discuss.
- Introduce more queue consumers — analytics, fulfillment, audit — to show the event fan-out pattern your system actually uses.
- Mark third-party dependencies like the email provider with a distinct styling class so external failure domains stand out.
Because visual edits regenerate clean Mermaid code, you can drag services into new subgraphs or reroute arrows in the editor and still commit readable, diff-friendly text to your architecture repo.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart LR
U[Users] --> LB[Load balancer]
LB --> GW[API gateway]
subgraph Services
GW --> AUTH[Auth service]
GW --> ORD[Orders service]
GW --> PAY[Payments service]
end
ORD --> DB1[(Orders DB)]
PAY --> DB2[(Payments DB)]
AUTH --> CACHE[(Session cache)]
ORD --> MQ[[Message queue]]
MQ --> NOTIF[Notification service]
NOTIF --> MAIL[Email provider]
Frequently asked questions
- What should a microservices architecture diagram include?
- At minimum: the entry path (load balancer and API gateway), each service as its own node, the data store each service owns, and any async infrastructure like message queues. This template covers all four, including the database-per-service pattern — Orders and Payments each get their own DB, which is the defining trait of real microservices.
- Why is the message queue important in this diagram?
- The queue between the Orders service and the Notification service shows asynchronous decoupling: placing an order does not block on sending an email. Drawing this explicitly helps reviewers spot which calls are synchronous request paths and which are fire-and-forget events — a distinction that drives latency budgets and failure handling.
- How is this different from a C4 or deployment diagram?
- This is a logical architecture view: it shows which components exist and how data flows, without committing to regions, clusters, or instance counts. C4 container diagrams add explicit boundaries and technology labels; deployment diagrams add infrastructure. Start here for whiteboard-level alignment, then add detail as decisions firm up.
- Can I render different shapes for databases and queues in Mermaid?
- Yes — this template already does. Cylinder syntax like DB1[(Orders DB)] renders databases, and double brackets like MQ[[Message queue]] render the queue as a subroutine shape. The subgraph block groups the three services visually. Reuse these shape conventions consistently and your diagrams become instantly readable.