Microservices on AWS: Architecture Diagram Examples
A microservices diagram fails for the opposite reason most diagrams fail: not too little information, but too much. Ten services, each with a database, a queue, and three synchronous dependencies, drawn on one canvas, produces the spaghetti diagram everyone has seen in a design review and nobody could read. This guide covers how to structure AWS microservices diagrams so they stay legible — what belongs at the system level versus the service level, how to draw API Gateway plus ECS or EKS request paths, how to use an event bus as a visual spine instead of a web of arrows, and a worked five-service e-commerce example you can adapt.
What should a microservices architecture diagram actually show?
The single most important decision is picking one altitude and staying there. A system-level diagram shows services as opaque boxes — the Order service, the Payment service — plus the shared infrastructure between them: API Gateway, the event bus, shared data stores. A service-level diagram zooms into one box and shows its internals: the ECS task definition, its DynamoDB table, its SQS dead-letter queue, its Secrets Manager entries. Mixing altitudes is what kills diagrams: the moment one service shows its internal Lambda functions while its neighbors are plain rectangles, the reader loses the ability to compare like with like.
In practice you need one system-level diagram and one service-level diagram per nontrivial service, not one mega-diagram. The system view answers questions like 'what happens when an order is placed?' and 'which services does checkout depend on synchronously?' The service view answers 'where does this service store state?' and 'what happens when its queue backs up?' These are different audiences too — the system view goes in the architecture doc and onboarding wiki; the service view lives with the team that owns the service.
A useful rule: if a component is only referenced by one service, it belongs in that service's diagram, not the system diagram. An RDS instance used solely by the Inventory service is service-level detail. The EventBridge bus that four services publish to is system-level structure. Applying this rule mechanically removes about half the boxes from a typical overloaded diagram.
How do you diagram API Gateway with ECS or EKS services?
The synchronous request path reads left to right: client, then Amazon API Gateway (or an Application Load Balancer for internal-facing paths), then the compute layer. For ECS, draw each service as a labeled box inside an ECS cluster container shape, with the ALB target group implied by the arrow rather than drawn as a separate node — target groups, listeners, and task definitions are configuration, not architecture, and they belong in Terraform, not the diagram. Use the official AWS icons: the purple API Gateway hexagon and the orange ECS icon are instantly recognizable and save you a label.
For EKS, the same pattern applies but the cluster container holds Kubernetes objects. At system level, still show one box per service — a Deployment name like orders-api — not per pod. Ingress controllers (ALB Ingress Controller or an NGINX ingress) sit at the cluster boundary where API Gateway or the ALB hands off. If you run a service mesh like App Mesh or Istio, do not draw sidecar proxies next to every service; instead add a single legend note saying 'all service-to-service traffic transits the mesh' and reserve mesh detail for a dedicated networking diagram. Drawing an Envoy sidecar sixteen times conveys nothing the note does not.
Label the arrows on the request path with protocol and route, not just direction: 'HTTPS /v1/orders' from API Gateway to the Orders service says far more than a bare line. Where API Gateway does request-level work — JWT authorization via a Cognito authorizer, throttling, request validation — annotate the gateway node itself rather than adding boxes, because those are features of the gateway, not separate components.
How do you diagram event-driven architecture with SQS, SNS, and EventBridge?
Event-driven systems are where spaghetti happens, and the fix is structural: draw the event bus as a horizontal spine across the middle of the canvas. Producers sit above it with arrows pointing down into the bus; consumers sit below it with arrows coming out. Each arrow gets an event name — OrderPlaced, PaymentCaptured, InventoryReserved — instead of a generic 'publishes' label. This layout means adding a new consumer adds exactly one arrow, whereas point-to-point layouts add N arrows for N interested services.
Distinguish the three messaging primitives visually because they have different semantics. EventBridge is the bus — the spine — for domain events routed by rule. SNS topics are fan-out points, useful when one event must reach several consumers with per-subscriber filtering. SQS queues are buffers owned by a single consumer, so draw each queue immediately adjacent to the service that drains it, inside that service's boundary if your notation allows containers. A queue floating in the middle of the diagram, equidistant from producer and consumer, hides the most important fact about it: who owns it.
Dead-letter queues deserve a deliberate choice. At system level, omit them — every SQS queue should have one, and a legend note stating that is cheaper than doubling your queue count on the canvas. At service level, draw the DLQ explicitly with its redrive policy (maxReceiveCount: 3) as an annotation, because that is exactly the operational detail an on-call engineer needs at 3 a.m.
How do you avoid spaghetti arrows in a microservices diagram?
Group services by business domain before you draw a single arrow. An e-commerce system has an ordering domain, a fulfillment domain, a customer domain — draw each as a container (a labeled swimlane or rounded rectangle) holding its services. Cross-domain arrows are the interesting ones architecturally, and grouping makes them visually distinct from chatty intra-domain calls. If you find a domain container with services that mostly talk outside their own container, the diagram has just surfaced a real boundary problem, which is the whole point of drawing it.
Ration synchronous arrows aggressively. Show a direct service-to-service call only when it is a genuine runtime dependency where the caller blocks on the response — these are your availability coupling points and deserve visual weight, ideally a solid line versus dashed lines for async event flows. Everything that flows through the event spine already has its arrow at the bus, so never duplicate it as a service-to-service line. A readable target: a ten-service system diagram should have fewer than fifteen arrows total. If you are past twenty, split by domain into separate diagrams.
Tooling affects how easy this discipline is to maintain. Mermaid is excellent for diagrams-in-git and PR review, but its automatic layout fights you on spine-and-swimlane structures beyond about eight nodes. Lucidchart handles containers and AWS icons well but is paid and produces files locked to its platform. Draw.io (diagrams.net) is free, has the full official AWS icon library, and stores diagrams as portable XML — its main cost is the manual labor of placing and re-placing boxes as the architecture evolves, which is the gap AI generation tools now target.
Worked example: an e-commerce system with 5 services
Take a concrete system: Storefront API, Orders, Payments, Inventory, and Notifications, running on ECS Fargate behind API Gateway, with EventBridge as the domain event bus. The system diagram lays out in three bands. Top band: the client, API Gateway with a Cognito authorizer annotation, and the Storefront API service, which is the only service exposed synchronously. Middle band: the EventBridge bus drawn as a full-width spine. Bottom band: Orders, Payments, Inventory, and Notifications as consumers and producers around the spine, grouped into an 'ordering' domain container (Orders, Payments) and a 'fulfillment' domain container (Inventory, Notifications).
The event flow reads directly off the spine. Storefront publishes OrderPlaced. Orders consumes it, writes to its DynamoDB table, and publishes OrderConfirmed. Payments consumes OrderPlaced, calls Stripe (drawn as an external system box outside the AWS boundary, connected with a dashed line), and publishes PaymentCaptured or PaymentFailed. Inventory consumes OrderConfirmed and publishes InventoryReserved. Notifications consumes PaymentCaptured and InventoryReserved and sends email via SES. Exactly one synchronous arrow exists below the top band: Storefront calls Inventory's GET /stock endpoint at checkout to display availability, and that solid line visually flags the one place where Inventory being down degrades checkout.
Count the elements: 5 service boxes, 1 gateway, 1 bus, 2 domain containers, 2 external systems (Stripe, SES), roughly 12 labeled arrows. Every event name is on its arrow, every queue is inside its owning service and therefore invisible at this level, and the whole thing fits on one screen. Each service then gets its own service-level diagram — Payments' would show its SQS input queue with DLQ, its Secrets Manager entry for the Stripe key, and its idempotency table — but none of that pollutes the system view.
Can AI generate an AWS microservices diagram from a text description?
Yes, and microservices diagrams are a strong fit for it, because the tedious part is not deciding the architecture — you already know it — it is placing forty shapes, wiring arrows, and finding the right AWS icons. AIDrawIO takes a plain-English description and generates a draw.io-compatible diagram using the official AWS architecture icon set, which you can then edit shape-by-shape in AIDrawIO itself or in diagrams.net, since the output is standard draw.io XML rather than a flat image.
A prompt that produces the worked example above: 'AWS microservices architecture diagram for e-commerce. API Gateway with Cognito authorizer routes to a Storefront API service on ECS Fargate. EventBridge bus as a horizontal spine. Below the bus: Orders, Payments, Inventory, Notifications services on ECS, grouped into ordering and fulfillment domain containers. Orders has a DynamoDB table. Payments calls Stripe (external). Notifications sends via SES. Label event arrows: OrderPlaced, OrderConfirmed, PaymentCaptured, InventoryReserved. One synchronous arrow from Storefront to Inventory labeled GET /stock.' Specifying the spine layout and the event names in the prompt is what keeps the generated result readable rather than auto-arranged.
The free tier at aidrawio.com/en/tools/aws-diagram-generator allows 5 generations per hour with no account, which covers a system diagram plus a couple of revision passes. Because output is editable XML with version history, the workflow that works in practice is: generate the skeleton, hand-adjust domain container placement, then regenerate individual service-level diagrams as separate files as the architecture changes. It also converts whiteboard photos and screenshots into editable vector diagrams, which is the fastest path from a design-review sketch to a diagram you can actually maintain.
Essayez gratuitement AWS generator
AI-generated AWS architecture diagrams. Describe in plain English, get draw.io XML in seconds. No account required.
Questions frequentes
What is the best way to diagram microservices on AWS?
Keep one system-level diagram showing services as opaque boxes around shared infrastructure (API Gateway, an EventBridge bus), plus separate service-level diagrams for internals like queues, tables, and DLQs. Group services into business-domain containers and draw the event bus as a horizontal spine so each new consumer adds one arrow instead of many.
Should I show SQS queues and dead-letter queues in my architecture diagram?
At system level, draw each SQS queue inside the service that consumes it and omit DLQs, replacing them with a legend note that every queue has one. At service level, show the DLQ explicitly with its redrive policy, since that is the detail on-call engineers actually need.
How do I diagram an event-driven architecture without it becoming spaghetti?
Use the event bus as a central spine: producers above with arrows in, consumers below with arrows out, and every arrow labeled with a concrete event name like OrderPlaced. Reserve solid direct service-to-service arrows for genuine synchronous dependencies, and split the diagram by domain once you pass roughly fifteen to twenty arrows.
What is the difference between a system-level and service-level microservices diagram?
A system-level diagram shows how services relate — gateways, the event bus, cross-service dependencies — with each service as a single box. A service-level diagram zooms into one service and shows its compute, data stores, queues, and secrets. A component referenced by only one service belongs in that service's diagram, not the system view.
Can I generate an AWS architecture diagram from a text description?
Yes. Tools like AIDrawIO generate draw.io-compatible XML from a plain-English prompt using official AWS icons, so the result stays fully editable in AIDrawIO or diagrams.net. Specify layout intent in the prompt — event bus as a spine, domain groupings, named event arrows — to get a readable diagram rather than an auto-arranged tangle.