Microservices Architecture Diagram: An Example and Seven Rules That Keep It Readable

Ask a team to draw their microservices and you often get the same picture: thirty boxes, every one connected to every other, arrows without labels. It is accurate, and it answers no question anyone has. Engineers call it the death star diagram.

A useful microservices architecture diagram is a set of decisions about what to show. This guide walks through one example, an online store with five services, and the seven rules that make it readable. The same rules work whether you have five services or fifty.

What the diagram has to answer

Before you draw, write down the questions. A good microservices diagram answers five of them at a glance:

1. Where do requests enter? Clients, the API gateway, backends for frontends.
2. Which service owns which data? Every database should have exactly one owner.
3. Who calls whom synchronously? These calls share latency and failures.
4. What happens asynchronously? Events and queues decouple services in time.
5. What is outside our control? Payment providers, email services, partner APIs.

If a box or an arrow does not help answer one of these, it probably belongs on another diagram.

The example: an online store with five services

The store has web and mobile clients, an API gateway and five services:

• Catalog serves products from its own PostgreSQL database.
• Cart keeps carts in Redis.
• Orders creates orders in its own PostgreSQL database and publishes OrderPlaced to the orders topic in Kafka.
• Payments consumes OrderPlaced, charges the card through Stripe, stores the result and publishes PaymentSucceeded or PaymentFailed to the payments topic.
• Notifications consumes the payments topic and emails a receipt, or a notice that the payment failed, through an email provider.

Orders also consumes the payments topic to mark an order as paid. Nobody calls Payments directly; the checkout flow is a chain of events. That design choice is exactly what the diagram must make visible:

Read it from left to right: the gateway is the only entry point, solid arrows are synchronous calls, dashed arrows are events through named topics, and every database hangs off exactly one service.

Seven rules for a readable microservices diagram

1. Start from the entry points

Draw clients and the API gateway first, on the left. They anchor the reading direction, and they show which services are exposed at all. A service with no path from the gateway is internal, and that is worth seeing.

2. Attach each database to its owner

Put each data store next to the one service that owns it and connect only that service. If two services share a database today, draw that too. It is a known smell, and a diagram that hides it makes the next migration harder to plan.

3. Separate synchronous calls from events

Use two line styles and say so in a legend: solid for request and response (REST, gRPC), dashed for messages through a broker. Draw the topics or queues as nodes. A single "event bus" box with every service attached hides who produces and who consumes what.

4. Label every edge with what flows

GET /products, POST /orders, OrderPlaced, PaymentFailed. A label turns an arrow into a contract, and it is what people search the diagram for during an incident.

5. Group by domain, not by technology

If you need frames, group services by business domain or owning team: shopping, checkout, customer communication. Frames such as "Node.js services" or "Java services" answer a question nobody asks.

6. Keep infrastructure in its own view

Pods, sidecars, service meshes and dashboards matter, but not on the logical view. Draw the deployment on a separate diagram, for example a Kubernetes architecture diagram, and link the two.

7. Show one critical flow

Pick the flow that pays the bills, here checkout, and make it easy to follow: number the steps on the edges or emphasize its path. One flow per diagram; a second flow gets its own copy of the view.

When the system is too big for one diagram

Past twenty or so boxes, split. A pattern that holds up:

• One landscape diagram with domains as frames and only the most important connections between them.
• One diagram per domain with its services, data stores and topics, drawn with the rules above.
• Flow diagrams for the few journeys that matter, such as checkout or sign-up.

This maps neatly onto the C4 model: the landscape is close to a system context view, and each domain diagram is a container view where services and their databases are containers.

Common mistakes

• Arrows without labels. Readers guess, and they guess differently.
• The gateway connected to databases. If it really reads a database, that is a design decision to discuss, not a shortcut to draw.
• Mixing views. Pods, AWS services and business capabilities on one canvas mean nobody can read any of them.
• Hiding the broker. Kafka is not a pipe; topics have names, owners and consumers.
• A snapshot that never changes. A diagram from the last re-architecture is a history document. Date it, or keep it live.

Build it in Archboard

Archboard has node packs for each part of this diagram, so services, stores and topics are typed nodes with ports instead of look-alike boxes:

1. Sign in with Google or GitHub and create a diagram.
2. Add a Box from the Core pack for the clients and an API Gateway from the Cloud pack.
3. Add the services as Container nodes from the C4 Model pack, with the language or framework in the technology field.
4. Add Postgres and Redis from the Data pack next to their owners, and Topic nodes for orders and payments.
5. Add External System nodes from the C4 Model pack for Stripe and the email provider.
6. Connect ports. Keep synchronous calls solid and set events to a dashed line, then label every edge.
7. Share the live link with the team, or embed it in your docs on Pro.

The example above has 15 diagram nodes, which fits the Free plan. For related examples, open /examples/kubernetes-microservices for the deployment side and /examples/api-gateway-infographic for an infographic of the gateway pattern.

FAQ

How many services should one diagram show? As many as you can read without zooming, usually up to about twenty boxes. Past that, split by domain and keep a landscape view on top.

Should I use the C4 model for microservices? It works well. Services and their databases become containers in a container view. Some teams model each independently owned service as its own software system; pick one convention and write it down.

How do I show Kubernetes, the service mesh and monitoring? On a separate deployment diagram. The logical view answers who talks to whom; the deployment view answers where it runs.

Should events point from the consumer to the topic, since consumers pull? Draw the direction the data flows, producer to topic to consumer, and note that consumers pull if it matters for the discussion.

How do I keep it current? Give the diagram an owner, update it in the same pull request as the change, and link the live diagram from your docs instead of pasting screenshots.

Start free — one seat, no credit card.