Skip to content
idocs
Get started

Open source · MIT · Astro and Starlight

Architecture diagrams you canpress playon.

Describe your system in YAML. idocs 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.

the i in idocs

  • interactiveClick a box, expand a card, press play on a request.
  • intuitivePlain YAML and automatic layout. No coordinates, no canvas to drag.
  • integratedIt lives in your repo and your docs site, and is checked at build time.
  • impressiveBrand icons, light and dark, and diagrams worth putting on a page.
Get startedOpen playground
$npm create idocs@latest my-docs
showcase12 nodes · 3 scenarios · 3 viewsThe real thing, not a screenshot. Click a box, expand a card, switch a view.
HTTP request / responseData accessQueue / brokerPersistent channel (websocket, gRPC)Audit trailDashed: planned
Loading diagram…
  • Click a box for its docs and a picture of what is inside
  • Expand a card to see its diagram in place, or open it
  • Play a scenario as packets, a sequence or a story
  • Switch views, hide what is planned, resize the viewer

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 idocs as the page loaded.

Name the parts and say who talks to whom. Pick a kind and an icon for each node and idocs 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…

Scenarios

One list of steps. Three ways to read it.

A scenario is a short list of steps: who sends what to whom. idocs 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
HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned
Loading diagram…

Make it yours

Restyle every diagram with a handful of CSS variables.

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

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned
Loading diagram…
src/styles/custom.css
/* Nothing to write: follows the site theme. */
.idocs {
  --idocs-accent: #0a6f8f;
}
src/styles/custom.css
.idocs {
  --idocs-bg: #0a2540;
  --idocs-surface: #0f3256;
  --idocs-zone: #0c2c4c;
  --idocs-ink: #e6f2ff;
  --idocs-muted: #9bbfe0;
  --idocs-line: #35689b;
  --idocs-accent: #7fd3ff;
}
src/styles/custom.css
.idocs {
  --idocs-bg: #050806;
  --idocs-surface: #0b110c;
  --idocs-zone: #08100a;
  --idocs-ink: #c9f7d3;
  --idocs-line: #1f4a2b;
  --idocs-accent: #4ade80;
  --idocs-sans: var(--idocs-mono);
}
src/styles/custom.css
.idocs {
  --idocs-bg: #fbfaf8;
  --idocs-surface: #ffffff;
  --idocs-zone: #f1f0ed;
  --idocs-ink: #121212;
  --idocs-line: #1f1f1f;
  --idocs-accent: #d4281c;
  --idocs-shadow: 3px 3px 0 #1f1f1f;
}

Dark mode takes its own set under :root[data-theme='dark'] .idocs. 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.

  • A published JSON Schema

    idocs 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. idocs check warns when one of them moves.

$npx skills add The-Package-Labs/idocs --skill idocs
About the skill

What is in the box

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

Automatic layout

Each zone is laid out on its own and every edge is routed around the boxes. You steer with a few hints, never with coordinates.

Scenarios that play

The happy path, a cache miss, a declined card. Step, scrub, change the speed, and share a link to the exact moment.

Story and sequence views

The same steps as swimlanes with phases, or as a sequence diagram. There is no second file to keep in sync.

One model, many views

Write a node once. Show it in an overview, a backend-only slice, or one view per team.

Docs inside the picture

Click a box for its markdown, its connections and its source files. An interfaces table is generated from the edges.

Diagrams inside diagrams

A box can hold a whole diagram. Click it for a picture, expand it in place as a group, or open it and find your way back.

Brand icons

Thousands of logos and UI icons are bundled at build time. Your own SVG files work too.

Themeable

Light and dark follow the site. Every colour, font and shadow is a CSS variable starting with --idocs-.

A viewer the reader controls

Pan, zoom, fit and full screen. Drag the bottom edge to resize it in the page, or expand it to most of the window.

Checked at build time

idocs check validates every diagram and the build fails on errors, so what is published always renders.

In your editor

A VS Code extension with a live preview, problems as you type, completion and rename across files.

Static and quick to publish

The output is a static Astro site. The starter ships a GitHub Pages workflow, and any static host works.

Get started

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 startSee a large example
  • MITFree to use and change.
  • Node 22+And pnpm.
  • Astro + StarlightMarkdown pages, search, dark mode.
  • Static outputAny host works.
  1. Create the project
    $npm create idocs@latest my-docs
  2. Run it
    $cd my-docs && pnpm install && pnpm dev
  3. 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.

  4. Publish

    Enable GitHub Pages with the GitHub Actions source and push. The workflow is already there.