How do I decide service boundaries before drawing?+
Draw boundaries around data ownership, not around code convenience. Each service should own its data and expose it only through its API. A practical test while diagramming: if a proposed service can't be deployed without simultaneously deploying another, the boundary is in the wrong place and the diagram should show them merged.
Should the diagram include databases per service?+
Yes — data ownership is the defining characteristic of microservices, so hiding it removes the most important information. Give each service its own datastore symbol, and if several genuinely share one, draw that shared dependency explicitly rather than quietly duplicating the icon.
How do I show async messaging and event buses?+
Draw the broker (Kafka, RabbitMQ, SQS) as a distinct element rather than as a line, then connect producers into it and consumers out of it. This matters because the broker decouples the two sides: producers don't know their consumers. A direct producer-to-consumer arrow would imply coupling that doesn't exist.
How detailed should a microservices diagram be for onboarding?+
For a new engineer, keep it to services, their datastores, the gateway, and the two or three most important call paths — ideally annotated with a real user request tracing through the system. Full inventory diagrams overwhelm newcomers; a single traced request teaches the architecture much faster.
How often should this diagram be updated?+
Tie updates to service-boundary changes, not to code changes. Adding an endpoint doesn't affect the diagram; splitting a service, introducing a broker, or changing who owns a datastore does. Put a last-reviewed date on it so readers know how much to trust it.
