Microservice Call Sequence
The code
sequenceDiagram
autonumber
actor C as Client
participant G as API Gateway
participant O as Order Service
participant I as Inventory Service
participant N as Notification Service
C->>G: POST order request
G->>O: Create order
O->>I: Reserve stock
I-->>O: Stock confirmed
O-->>G: Order created
G-->>C: 201 response
O->>N: Emit order event
N-->>O: Event acknowledged
Note over G,N: All services share one trace id
How this template works
This template shows how one user request fans out across a microservice backend. A client call hits the API gateway, which forwards it to the order service, which reserves stock in the inventory service; the responses then unwind back up the chain, and only after the client has received its answer does the order service emit the event that the notification service consumes. That split — synchronous hops for the answer, an asynchronous event for the side effects — is the single most important idea in the diagram, and it is what makes sequence diagrams the standard artifact for reviewing service boundaries.
The syntax demonstrates a five-lifeline conversation. sequenceDiagram declares the type and autonumber numbers the messages, which is invaluable when a reviewer says “step 6 is where the latency comes from.” Lifelines are declared in call order: actor C as Client, then participant G as API Gateway, participant O as Order Service, participant I as Inventory Service, and participant N as Notification Service. The nested calls read as indentation in time — O->>I: Reserve stock happens while the gateway is still waiting on the order service. The response chain I-->>O, O-->>G, and G-->>C: 201 response unwinds in reverse order, and the dashed arrows make the unwinding visible. The event exchange O->>N: Emit order event appears after the client response, deliberately drawn out of the request’s critical path. The closing Note over G,N: All services share one trace id spans the backend lifelines to record the observability contract.
The gotcha is width. Five lifelines with long display names produce a diagram that scrolls horizontally on a phone, so keep the as aliases short and put the detail in the message text instead. The second trap is drawing the event exchange before the client response — that would claim the notification blocks the user, which is exactly the coupling this architecture avoids.
To adapt it, rename the services to your domain, add the failure branch for the stock reservation in an alt block, and add a compensation message if your flow uses sagas.
Related templates: the api auth sequence covers the authentication in front of the gateway, the database transaction sequence zooms into what one service does at the data layer, and the websocket chat sequence shows a push-based alternative to request and response. The sequence diagram guide documents the full syntax.
Variations to try
- Add an alt block around the stock reservation for the out-of-stock case and its compensation step.
- Move the notification exchange into a loop if your event bus redelivers until it gets an ack.
- Rename the services to your actual domain, such as billing and shipping, before adding to a runbook.
