The Diagram component

<Diagram> puts a diagram on any .mdx page or .astro file. The diagram loads when it scrolls into view, so a page with several diagrams stays fast. Until then the page holds a placeholder, because card heights are measured in the browser.

import Diagram from '@packagelab/docspp-astro/Diagram.astro'

<Diagram name="checkout" />

Online store checkout

How a shopper's browser reaches the store, what the backend does with each request, and where things can go wrong. Click any box for details, or pick a scenario above the diagram and press play to watch a request travel through the system.

OverviewBackend only

Everything in one picture. Letters on the edges match the interfaces table underneath.

ScenarioOverviewBrowse a product (cache hit)Browse a product (cache miss)Place an orderCard declined

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

Key	From → To	Kind	Auth	What travels
A	Shopper browser → CDN	http	—	HTTPS
B	CDN → API gateway	http	—	—
C	API gateway → Keycloak	data	client credentials	signing keys
D	API gateway → catalog-service	http	—	/products
E	API gateway → cart-service	http	—	/cart
F	API gateway → order-service	http	—	/orders
G	catalog-service → Redis	data	—	cache
H	catalog-service → PostgreSQL	data	—	—
I	cart-service → Redis	data	—	—
J	order-service → PostgreSQL	data	—	—
K	order-service → Stripe	channel	API key	payment intent
L	order-service → RabbitMQ	queue	—	order.created
M	RabbitMQ → notification-worker	queue	—	—

Shopper browser

React storefront

CDN

static assets · TLS

API gateway

:443 · rate limit

verifies the JWT

routes by path

Keycloak

OIDC · realm shop

catalog-service

:4001 · Node.js

products

prices

search

uses: redis · postgres

cart-service

:4002 · Go

session carts

uses: redis

order-service

:4003 · .NET

creates and tracks orders

talks to the payment provider

uses: postgres · rabbitmq

notification-worker

email and push

planned

Redis

catalog cache · carts

PostgreSQL

orders · products

RabbitMQ

order.events

Stripe

payment provider

name is the folder name under diagrams/. If it does not match, the build stops with the names that exist: <Diagram name="chekout"> does not match a diagram. Available: checkout, payments, platform.

Props

Prop	Type	Meaning
name	string	Required. The folder under diagrams/.
view	string	The view to show first. Defaults to the diagram’s first view.
scenario	string	The scenario to select first. It waits for the reader unless you add autoplay.
mode	flow, sequence or story	How the scenario is shown. Defaults to the scenario’s own mode, then flow.
autoplay	boolean	Play scenario as soon as the diagram is laid out.
maxHeight	number	The tallest the canvas may grow before it scrolls inside its frame, in pixels. Default 780.
showTitle	boolean	Show the diagram’s title above it.
showDescription	boolean	Show the diagram’s description above the first view.
hash	boolean	Keep the scenario and step in the address bar. Default true.

See the props reference for the same list in one table.

Examples

<Diagram name="checkout" view="backend" />
<Diagram name="checkout" view="backend" scenario="place-order" />
<Diagram name="checkout" scenario="place-order" mode="sequence" />
<Diagram name="checkout" scenario="place-order" mode="story" />
<Diagram name="checkout" showDescription />

Open on a scenario, and play it

OverviewBackend only

Everything in one picture. Letters on the edges match the interfaces table underneath.

ScenarioOverviewBrowse a product (cache hit)Browse a product (cache miss)Place an orderCard declined

The payment provider refuses the card. The order stays pending and the shopper is told why.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

ISubmit and charge

1

Shopper browser→order-servicevia CDN, API gatewayPOST /orders

2

order-service→PostgreSQLINSERT order (pending)

3

order-service→Stripecreate payment intent

IIDeclined

4

Stripe→order-servicecard_declined

5

order-servicemark order failed

6

order-service→Shopper browservia API gateway, CDN402 Payment Required

The response carries the decline code so the storefront can show a helpful message.

Key	From → To	Kind	Auth	What travels
A	Shopper browser → CDN	http	—	HTTPS
B	CDN → API gateway	http	—	—
C	API gateway → Keycloak	data	client credentials	signing keys
D	API gateway → catalog-service	http	—	/products
E	API gateway → cart-service	http	—	/cart
F	API gateway → order-service	http	—	/orders
G	catalog-service → Redis	data	—	cache
H	catalog-service → PostgreSQL	data	—	—
I	cart-service → Redis	data	—	—
J	order-service → PostgreSQL	data	—	—
K	order-service → Stripe	channel	API key	payment intent
L	order-service → RabbitMQ	queue	—	order.created
M	RabbitMQ → notification-worker	queue	—	—

Shopper browser

React storefront

CDN

static assets · TLS

API gateway

:443 · rate limit

verifies the JWT

routes by path

Keycloak

OIDC · realm shop

catalog-service

:4001 · Node.js

products

prices

search

uses: redis · postgres

cart-service

:4002 · Go

session carts

uses: redis

order-service

:4003 · .NET

creates and tracks orders

talks to the payment provider

uses: postgres · rabbitmq

notification-worker

email and push

planned

Redis

catalog cache · carts

PostgreSQL

orders · products

RabbitMQ

order.events

Stripe

payment provider

<Diagram name="checkout" scenario="payment-declined" autoplay hash={false} />

autoplay suits one diagram near the top of a page. Readers who ask their system for reduced motion are never autoplayed. Use hash={false} on embeds that should not change the address bar, such as a demo.

Open on a story

<Diagram name="platform" scenario="request-story" mode="story" />

Without mode, a scenario opens the way its own mode: says. With mode, the page decides. The reader can still switch with the buttons beside the player.

Show the description

showDescription puts the diagram’s description (Markdown, from the YAML) above the views. Examples pages use it to explain what to click.

The page around it

A diagram wants room. @packagelab/docspp-astro/starlight.css widens Starlight’s content column and holds ordinary text to a readable width, while diagrams use the full width. Add it to Starlight’s customCss:

starlight({
  customCss: ['@packagelab/docspp-astro/starlight.css'],
})

For a page that is only a diagram, hide the table of contents so the column is as wide as it can be:

---
title: Online store checkout
tableOfContents: false
---

Tip

Do not repeat the diagram in prose. Use the page for what the diagram cannot say: why a choice was made, what to watch for and who to ask.

Linking to a moment

When hash is on (the default), the address bar follows the selected scenario and step, so readers can share a link to what they are looking at. Opening such a link restores it. The format is #<diagram>=<scenario>[.<step>]. See playback.

You can write these links yourself in your prose:

[the declined card](/examples/checkout/#checkout=payment-declined.3)

In an Astro page

<Diagram> is an ordinary Astro component, so it works in .astro files as well:

---
import Diagram from '@packagelab/docspp-astro/Diagram.astro'
---

<Diagram name="shop" scenario="checkout" />

Do not add a client: directive to it. The component already loads its interactive part with client:visible.