Microservice request flow
API gateway fanning out to services with a cache.
When someone asks "what actually happens when a client requests an order?", this is the diagram that answers it. One GET request travels through the API gateway to the Orders Service, which checks the cache, falls back to the database on a miss, repopulates the cache, publishes an analytics event, and returns JSON — six participants, one complete story.
The alt block is the heart of the template. Read-through caching is easy to describe and easy to get wrong; drawing the hit and miss branches side by side makes the write-back step explicit, which is precisely the step that gets forgotten in implementation and code review.
When to use this template
- Architecture documentation — a single representative request often explains a system better than a component diagram, because it shows order, direction, and the conditional paths boxes-and-arrows can't express.
- Latency investigations — annotate each arrow with measured timings and the slow hop jumps out. The cache-miss branch shows exactly which calls only happen on the slow path.
- Design reviews for new endpoints — sketch the proposed call chain before building it, so reviewers can challenge the caching strategy or the event publish timing while changes are still cheap.
How to adapt it
Rename the Orders Service to your own domain and adjust the request to a real endpoint, then tune the infrastructure to match your stack:
- Add an auth check at the gateway — a self-call note or a hop to an auth service before the request is forwarded.
- Wrap the database call in a second alt block for the not-found case, returning a 404 through the same lifelines.
- Add a consumer participant after the event bus if you want to show who reacts to order.viewed.
The visual editor lets you add participants and reroute messages by dragging, and visual edits regenerate clean Mermaid code — so the diagram stays in sync with the version you commit next to the service's README.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant C as Client
participant G as API Gateway
participant S as Orders Service
participant R as Cache
participant D as Database
participant Q as Event Bus
C->>G: GET /orders/42
G->>S: Forward request
S->>R: Lookup order 42
alt Cache hit
R-->>S: Cached order
else Cache miss
S->>D: SELECT order 42
D-->>S: Order row
S->>R: Store in cache
end
S->>Q: Publish order.viewed
S-->>G: 200 OK
G-->>C: Order JSON
Frequently asked questions
- How do I diagram a microservice request flow?
- Give each infrastructure component its own participant — client, gateway, service, cache, database, event bus — and trace one request top to bottom. Use solid arrows for calls and dashed arrows for responses, and wrap conditional behavior like cache hits in an alt block. One well-chosen request usually documents the whole architecture better than a box diagram.
- What does the alt block mean in a Mermaid sequence diagram?
- An alt block shows mutually exclusive branches — exactly one executes per request. Here it captures the cache hit path (return the cached order) versus the cache miss path (query the database, then write the result back to the cache). Mermaid renders the branches as labeled compartments, so the read-through caching pattern is legible without any prose.
- Why is the event bus publish drawn before the response is returned?
- The diagram shows the Orders Service publishing order.viewed and then responding with 200 OK, which documents fire-and-forget eventing: the service doesn't wait for consumers. If your system publishes asynchronously after responding, swap the two arrows — the ordering in a sequence diagram is a real architectural claim, so make it match production.
- How many participants should a microservice sequence diagram have?
- Five to seven is the sweet spot. This template's six — client, gateway, service, cache, database, event bus — cover a complete request without crowding the page. If you need more, you're probably documenting two interactions; split them into separate diagrams that each answer one question, like 'how does a read work?' versus 'how does checkout fan out?'