Open source · MIT · Astro and Starlight

Architecture diagrams you canpress playon.

Describe your system in YAML. docspp lays it out, documents every box, and replays a request travelling through it, one step at a time. Readers see how it works instead of guessing.

Get started Open playground

$npm create docspp@latest my-docs

checkout12 nodes · 4 scenarios · 2 viewsThe real thing, not a screenshot. Click a box, or hold Ctrl or ⌘ and scroll to zoom.

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

Scenario

The shopper pays. The order is stored first, charged second, and announced to the rest of the system last.

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

Loading diagram…

ISubmit

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

The gateway has already checked the token, so the order service trusts the user id header.

order-service→PostgreSQLINSERT order (pending)

IICharge

order-service→Stripecreate payment intent

Stripeauthorise card

Stripe→order-servicesucceeded

IIIFinish

order-service→PostgreSQLmark paid

order-service→RabbitMQorder.created

order-service→Shopper browservia API gateway, CDN201 Created

RabbitMQ→notification-workerorder.createdplanned

Planned. Confirmation emails are not sent yet.

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	—	—

How it works

Write the model. The picture, the docs and the replay follow.

One YAML file per diagram. Add a concept at a time and watch what it buys you. Each tab below is a real file, compiled and drawn by docspp as the page loaded.

Name the parts and say who talks to whom. Pick a kind and an icon for each node and docspp draws the cards. Edges become arrows, and the legend is generated. There are no coordinates in the file.

diagrams/photos/diagram.yaml

title: Photo uploads

nodes:
  browser: { kind: client, icon: react }
  api:     { kind: service, icon: nodejs, title: Upload API }
  store:   { kind: storage, icon: aws-s3, title: Storage }
  queue:   { kind: queue, icon: rabbitmq, title: Events }
  worker:  { kind: worker, icon: python, title: Thumbnailer }
  db:      { kind: database, icon: postgresql, title: Metadata }

edges:
  - browser -> api: POST /photos
  - api -> store: { kind: data, label: PUT }
  - api -> db: { kind: data, label: SQL }
  - api -> queue: { kind: queue, label: photo.uploaded }
  - queue -> worker: { kind: queue }
  - worker -> store: { kind: data, label: PUT }
  - worker -> db: { kind: data }

views:
  overview: { direction: DOWN }

HTTP request / responseData accessQueue / broker

Loading diagram…

Group related parts into a zone. A group is one line and a node joins it with in:. Each zone is laid out on its own, so the diagram stays tidy as it grows.

diagrams/photos/diagram.yaml8 new lines

title: Photo uploads

groups:
  app: { label: Photo service, caption: Kubernetes }

nodes:
  browser: { kind: client, icon: react }
  api:     { kind: service, icon: nodejs, title: Upload API, in: app }
  store:   { kind: storage, icon: aws-s3, title: Storage, in: app }
  queue:   { kind: queue, icon: rabbitmq, title: Events, in: app }
  worker:  { kind: worker, icon: python, title: Thumbnailer, in: app }
  db:      { kind: database, icon: postgresql, title: Metadata, in: app }

edges:
  - browser -> api: POST /photos
  - api -> store: { kind: data, label: PUT }
  - api -> db: { kind: data, label: SQL }
  - api -> queue: { kind: queue, label: photo.uploaded }
  - queue -> worker: { kind: queue }
  - worker -> store: { kind: data, label: PUT }
  - worker -> db: { kind: data }

views:
  overview: { direction: DOWN }

HTTP request / responseData accessQueue / broker

Loading diagram…

Tell the story as steps. A packet flies along your edges, hop by hop, and every step is listed under the picture. Pause, scrub, or click a step to jump to it.

diagrams/photos/diagram.yaml12 new lines

title: Photo uploads

groups:
  app: { label: Photo service, caption: Kubernetes }

nodes:
  browser: { kind: client, icon: react }
  api:     { kind: service, icon: nodejs, title: Upload API, in: app }
  store:   { kind: storage, icon: aws-s3, title: Storage, in: app }
  queue:   { kind: queue, icon: rabbitmq, title: Events, in: app }
  worker:  { kind: worker, icon: python, title: Thumbnailer, in: app }
  db:      { kind: database, icon: postgresql, title: Metadata, in: app }

edges:
  - browser -> api: POST /photos
  - api -> store: { kind: data, label: PUT }
  - api -> db: { kind: data, label: SQL }
  - api -> queue: { kind: queue, label: photo.uploaded }
  - queue -> worker: { kind: queue }
  - worker -> store: { kind: data, label: PUT }
  - worker -> db: { kind: data }

views:
  overview: { direction: DOWN }

scenarios:
  upload:
    title: Upload a photo
    steps:
      - browser -> api: POST /photos
      - api -> store: { label: PUT original, kind: lookup }
      - api -> queue: { label: photo.uploaded, kind: event }
      - api -> browser: 202 Accepted
      - queue -> worker: photo.uploaded
      - worker -> store: PUT thumbnails
      - worker -> db: { label: mark ready, kind: lookup }

Scenario

HTTP request / responseData accessQueue / broker

Loading diagram…

browser→Upload APIPOST /photos

Upload API→StoragePUT original

Upload API→Eventsphoto.uploaded

Upload API→browser202 Accepted

Events→Thumbnailerphoto.uploaded

Thumbnailer→StoragePUT thumbnails

Thumbnailer→Metadatamark ready

Show a slice of the same model. The processing view keeps four of the six boxes and plays its own scenario. Nothing was redrawn.

diagrams/photos/diagram.yaml12 new lines

title: Photo uploads

groups:
  app: { label: Photo service, caption: Kubernetes }

nodes:
  browser: { kind: client, icon: react }
  api:     { kind: service, icon: nodejs, title: Upload API, in: app }
  store:   { kind: storage, icon: aws-s3, title: Storage, in: app }
  queue:   { kind: queue, icon: rabbitmq, title: Events, in: app }
  worker:  { kind: worker, icon: python, title: Thumbnailer, in: app }
  db:      { kind: database, icon: postgresql, title: Metadata, in: app }

edges:
  - browser -> api: POST /photos
  - api -> store: { kind: data, label: PUT }
  - api -> db: { kind: data, label: SQL }
  - api -> queue: { kind: queue, label: photo.uploaded }
  - queue -> worker: { kind: queue }
  - worker -> store: { kind: data, label: PUT }
  - worker -> db: { kind: data }

views:
  overview: { title: Everything, direction: DOWN }
  processing:
    title: Processing only
    include: [queue, worker, store, db]

scenarios:
  upload:
    title: Upload a photo
    steps:
      - browser -> api: POST /photos
      - api -> store: { label: PUT original, kind: lookup }
      - api -> queue: { label: photo.uploaded, kind: event }
      - api -> browser: 202 Accepted
      - queue -> worker: photo.uploaded
      - worker -> store: PUT thumbnails
      - worker -> db: { label: mark ready, kind: lookup }
  thumbnails:
    title: Make thumbnails
    view: processing
    steps:
      - queue -> worker: photo.uploaded
      - worker -> store: { label: GET original, kind: lookup }
      - worker -> store: PUT 3 sizes
      - worker -> db: { label: mark ready, kind: lookup }

Scenario

Queue / brokerData access

Loading diagram…

Events→Thumbnailerphoto.uploaded

Thumbnailer→StorageGET original

Thumbnailer→StoragePUT 3 sizes

Thumbnailer→Metadatamark ready

Scenarios

One list of steps. Three ways to read it.

A scenario is a short list of steps: who sends what to whom. docspp turns it into packets over the architecture, a sequence diagram or a swimlane story, and keeps all three in step with the player.

paymentsPay with a card · 3 phases · 9 steps

Scenario

The shopper pays. We write the payment down first, charge the card second, and tell the rest of the system last, so a crash never loses money.

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

Loading diagram…

IRecord itbefore any money moves

Web app→Payments APIPOST /payments

The request carries an idempotency key, so a retry cannot charge twice.

Payments API→Ledger databaseINSERT payment (pending)

IICharge the card

Payments API→Stripecreate payment intent

Stripeauthorise card

This is the only step we do not control, and the slowest one.

Stripe→Payments APIsucceeded

IIIFinish

Payments API→Ledger databasemark paid

Payments API→RabbitMQpayment.succeeded

Payments API→Web app201 Created

RabbitMQ→Receipt mailerpayment.succeededplanned

Receipts are planned. Today the shopper only sees the on-screen confirmation.

Make it yours

Restyle every diagram with a handful of CSS variables.

Every colour, font and shadow in a diagram is a --docspp-* token. Pick a palette and the diagram below changes. The snippet beside it is all the CSS that did it.

Scenario

The shopper pays. We write the payment down first, charge the card second, and tell the rest of the system last, so a crash never loses money.

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

Loading diagram…

IRecord itbefore any money moves

Web app→Payments APIPOST /payments

The request carries an idempotency key, so a retry cannot charge twice.

Payments API→Ledger databaseINSERT payment (pending)

IICharge the card

Payments API→Stripecreate payment intent

Stripeauthorise card

This is the only step we do not control, and the slowest one.

Stripe→Payments APIsucceeded

IIIFinish

Payments API→Ledger databasemark paid

Payments API→RabbitMQpayment.succeeded

Payments API→Web app201 Created

RabbitMQ→Receipt mailerpayment.succeededplanned

Receipts are planned. Today the shopper only sees the on-screen confirmation.

src/styles/custom.css

/* Nothing to write: follows the site theme. */
.docspp {
  --docspp-accent: #0a6f8f;
}

src/styles/custom.css

.docspp {
  --docspp-bg: #0a2540;
  --docspp-surface: #0f3256;
  --docspp-zone: #0c2c4c;
  --docspp-ink: #e6f2ff;
  --docspp-muted: #9bbfe0;
  --docspp-line: #35689b;
  --docspp-accent: #7fd3ff;
}

src/styles/custom.css

.docspp {
  --docspp-bg: #050806;
  --docspp-surface: #0b110c;
  --docspp-zone: #08100a;
  --docspp-ink: #c9f7d3;
  --docspp-line: #1f4a2b;
  --docspp-accent: #4ade80;
  --docspp-sans: var(--docspp-mono);
}

src/styles/custom.css

.docspp {
  --docspp-bg: #fbfaf8;
  --docspp-surface: #ffffff;
  --docspp-zone: #f1f0ed;
  --docspp-ink: #121212;
  --docspp-line: #1f1f1f;
  --docspp-accent: #d4281c;
  --docspp-shadow: 3px 3px 0 #1f1f1f;
}

Dark mode takes its own set under :root[data-theme='dark'] .docspp. Every token is listed in the theming guide.

Icons

Your stack is already in the box.

icon: postgresql finds the logo. Brand logos, monochrome marks and generic UI icons are bundled at build time, so nothing is fetched in the browser. How icons are found.

postgresql
redis
kafka
rabbitmq
kubernetes
docker
nginx
terraform
grafana
prometheus
elasticsearch
mongodb
nodejs
go
python
rust
typescript
react
astro
graphql
cloudflare
stripe
keycloak
github-actions

For people and agents

Plain YAML that an agent can write and a machine can check.

The format is small, the schema is published and the validator is strict. Ask Claude Code, Cursor or Copilot to draw your architecture, and the loop below keeps the result honest.

claude code diagrams/checkout

you    Add a diagram of how checkout works. The code is in services/.
       Include a scenario for a declined card.

claude Reading services/orders, services/catalog and the gateway config.
       Wrote diagrams/checkout/diagram.yaml  (12 nodes, 4 scenarios)

$ pnpm docspp check
diagrams/checkout/diagram.yaml:8:29  warning  Unknown icon "strpe"
    Run `docspp icons search <name>` to find one.
diagrams/checkout/diagram.yaml:13:5  error  Edge to "paymnts" is not a node
1 diagram compiled in .: 1 error, 1 warning

claude Two typos. Fixing both and checking again.

$ pnpm docspp check
1 diagram compiled in .: 0 errors, 0 warnings

A published JSON Schema
docspp schema writes it next to your diagrams. Editors autocomplete every key, and agents stop guessing them.
Errors that say where
File, line and column, with a hint that spells the right key. Add --json and a script can read them.
A broken diagram never ships
The build fails on diagram errors, so a typo is caught on the pull request and not on the live site.
References that notice drift
List the source files a box is based on. docspp check warns when one of them moves.

$npx skills add AhmeddBasemm/docspp --skill docspp

About the skill

What is in the box

Everything a diagram needs to be read, trusted and kept up to date.

One command to a running docs site.

The starter has a small shop diagram with three scenarios, a docs site around it and a GitHub Pages workflow. Edit the YAML, save, and the page reloads.

Read the quick start See a large example

MITFree to use and change.
Node 22+And pnpm.
Astro + StarlightMarkdown pages, search, dark mode.
Static outputAny host works.

Create the project
$npm create docspp@latest my-docs
Run it
$cd my-docs && pnpm install && pnpm dev
Draw your system
Open diagrams/shop/diagram.yaml, rename a node, add an edge, press save. Or ask an agent to write the diagram from your code.
Publish
Enable GitHub Pages with the GitHub Actions source and push. The workflow is already there.

Architecture diagrams you canpress playon.

Write the model. The picture, the docs and the replay follow.

One list of steps. Three ways to read it.

Restyle every diagram with a handful of CSS variables.

Your stack is already in the box.

Plain YAML that an agent can write and a machine can check.

Everything a diagram needs to be read, trusted and kept up to date.

Automatic layout

Scenarios that play

Story and sequence views

One model, many views

Docs inside the picture

Brand icons

Themeable

Checked at build time

Static and quick to publish

One command to a running docs site.