What is docspp

docspp is a tool for documentation sites. You describe a system in a YAML file. docspp lays the diagram out, draws it, documents every box, and can replay a request travelling through it, step by step.

The diagrams are not images. They are part of the page, so readers can click, filter and play them.

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 product is not cached yet, so the catalogue reads PostgreSQL and fills the cache for the next shopper.

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

Loading diagram…

IThe request

1

Shopper browser→catalog-servicevia CDN, API gatewayGET /products/42

IICache miss

2

catalog-service→RedisGET product:42

3

Redis→catalog-servicemiss

4

catalog-service→PostgreSQLSELECT product

5

PostgreSQL→catalog-servicerow

6

catalog-serviceSET product:42 ttl 60s

The next request for this product is a hit.

IIIThe answer

7

catalog-service→Shopper browservia API gateway, CDN200 + JSON

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

Press Play above, or click any box. Everything on the page, from the cards to the step list under the picture, was generated from one YAML file.

What readers get

• A diagram they can explore. Hover a box to follow its connections. Click it to read its documentation, see where it connects and find the source files it is based on.
• Stories, not just pictures. Scenarios replay a request through the system: the happy path, a cache miss, a declined card. Readers can pause, step, scrub, change the speed and share a link to the exact moment.
• The right amount of detail. Views show a slice of the same model: the whole system, the backend only, one team’s part.
• Light and dark. Diagrams follow the site theme and are styled with a few CSS variables.

What you write

You write a model, some views of it, and scenarios that play over a view. Each thing is written once and reused.

Part	What it is	Where it lives
Model	The nodes (boxes), groups (zones) and edges (arrows) of your system.	diagram.yaml
Views	Slices of the model. Without any, one view shows everything.	diagram.yaml
Scenarios	Ordered steps that play over a view.	diagram.yaml, or one file each in scenarios/
Node docs	Markdown shown when a reader clicks a box.	nodes/<id>.md

There are no coordinates in any of it. Layout is automatic, and you steer it with a few hints when the default is not what you want. How layout works explains the hints.

nodes:
  browser: { kind: client, title: Browser }
  api:     { kind: service, icon: nodejs, title: API, sub: ":3000" }
  db:      { kind: database, icon: postgresql, title: Database }

edges:
  - browser -> api: HTTPS
  - api -> db: { kind: data, label: SQL }

scenarios:
  load-page:
    title: Load a page
    steps:
      - browser -> api: GET /items
      - api -> db: { label: SELECT, kind: lookup }
      - db -> api: rows
      - api -> browser: 200 OK

How the pieces fit

The compiler runs once, on the server, when you build the site. It validates the YAML and turns it into plain JSON. The browser receives that JSON, lays the diagram out, and plays scenarios with a small clock. Pick the scenario below to follow one diagram through the whole pipeline.

ScenarioOverviewFrom YAML to a playing diagram

The compiler runs once, on the server. Everything the browser needs arrives as JSON, and playback is a clock over a pure function.

HTTP request / responseData access

Loading diagram…

IWrite

1

diagram.yamlyou edit the file

Nodes, edges, views and scenarios. No coordinates.

2

diagram.yaml→Compilerparse and validate

Every error carries file:line:col and, where it can, a suggestion.

3

nodes/<id>.md→Compilernode docs

IICheck

4

Compiler→docspp checkdiagnostics

5

Compiler→Astro integrationcompiled diagrams

In astro build an error here stops the build, so a broken diagram never reaches the site.

6

Astro integration→CompiledDiagramserialise

IIIDraw

7

CompiledDiagram→<Diagram> islandprops

The island loads when the diagram scrolls into view.

8

<Diagram> island→Layoutmeasure cards

Cards are rendered offscreen at their fixed width so their real heights are known.

9

Layout→Canvas and playerpositions and routes

10

<Diagram> island→Timelinebuild the timeline

11

Timeline→Canvas and playerframe at t

12

Canvas and player→Readerpackets fly

diagram.yaml

nodes · edges · scenarios

nodes/<id>.md

shown when a box is clicked

Compiler

parse · validate · compile

shorthand expanded

icons bundled

markdown rendered

docspp check

errors with file:line:col

Astro integration

virtual:docspp/diagrams

fails the build on errors

CompiledDiagram

plain JSON

<Diagram> island

hydrates when visible

Layout

measure · ELK per zone · router

Timeline

frameAt(t) is pure

Canvas and player

packets · steps · drawer

Reader

How it works inside describes each stage.

When to use it

docspp suits diagrams that explain how a system behaves: which service calls which, what travels over each line, and what happens when something fails. It works well for platform and architecture documentation, onboarding guides, runbooks and design reviews.

It is not a drawing tool. You cannot drag boxes to a position, and very large diagrams (more than about 30 nodes) render small until the reader zooms. If you need a free-form whiteboard or pixel-exact artwork, use a drawing tool. If you want diagrams that stay in git, review like code and cannot drift from the text around them, use docspp.

Where to go next

Quick startCreate a project and see it running in a minute.

Your first diagramBuild a small diagram step by step, from nodes to a playing scenario.

Diagram formatEvery field of nodes, groups, edges and views.

ScenariosTell the story of a request, step by step.