Drawing a Microservices Architecture

Draw capabilities, not code modules

Each box should be something a team could own end to end: orders, catalogue, identity. If the box names read like technical layers, such as controller or repository, you are drawing a single service from the inside. Zoom out until every box has its own deployment and its own data.

Make data ownership visible

Attach each service to its own database with a short, unambiguous line. If two services point at one database, the diagram is telling you something uncomfortable, and it should stay visible rather than be hidden. Shared data is the most common source of hidden coupling in these systems.

Distinguish synchronous and asynchronous calls

Use solid arrows for request and response calls, and dashed arrows or an explicit queue shape for events. Readers need to know which failures propagate immediately and which are absorbed by a broker. Label event arrows with the event name instead of the verb, for example order created.

Keep the gateway and cross-cutting parts quiet

Authentication, logging and tracing touch every service. Draw them once, at the edge or as a band underneath, rather than adding an arrow from each service. The microservices template uses a single gateway for this reason. If you need to show the full mesh, make it a second page so the first remains readable.

Common mistakes to avoid

Three habits make microservice diagrams misleading. Drawing every instance instead of the service hides the real boundaries. Drawing only the happy path hides the failure handling that defines the system. And drawing today's design as if it were permanent invites arguments later. Date the diagram, say what it is meant to show, and keep older versions in history so the evolution stays visible.

Try it with a template

• Microservices with API Gateway
• Backend for Frontend
• Strangler Fig Migration