Your first diagram

Install iso-topology, render a D2 diagram, and open the same source in Studio.

You need Go 1.25 or later on macOS, Linux, or Windows. For the library install and build-from-source options, see Installation.

1. Install the CLI

go install github.com/MarkovWangRR/iso-topology/cmd/isotopo@main

Make sure your Go binary directory ($GOBIN, or $(go env GOPATH)/bin by default) is on your PATH. Run isotopo capabilities to verify the installation.

These docs track the main branch. Use @main for the features documented here, or @latest for the newest tagged release, which may have fewer features.

The Go module path is still github.com/MarkovWangRR/iso-topology. The source repository now lives at MishaBear94/iso-topology.

2. Describe a small architecture

Create a file called services.d2:

services.d2

user: User { shape: person }
api: API Gateway
worker: Worker
db: Database { shape: cylinder }

user -> api: HTTPS
api -> worker: enqueue
worker -> db: write

D2 computes the layout from the graph. The renderer turns the nodes into isometric shapes and draws their connections.

3. Render it

isotopo render services.d2 ./out

Open out/topology.html in your browser to inspect the diagram. Use out/topology.svg wherever you need a vector image.

To inspect the same architecture from above, run isotopo render --projection top services.d2 ./out-plan.

4. Refine it in Studio

isotopo serve services.d2

Open http://localhost:8731. Studio provides a live source editor, canvas interactions, and export tools. See the Studio guide for the supported editing operations and save behavior.

5. Check and share

isotopo validate services.d2

Validation returns structured issues with paths and suggestions. Exit code 0 means clean, 2 means warnings, and 3 means errors. A diagram can render with warnings; inspect those warnings before publishing it.

Keep services.d2 in version control. Embed the generated SVG in your README:

![Service architecture](./out/topology.svg)

Add groups and boundaries

Continue the tutorial with nested services and labeled containers.

Browse example sources

Start from an existing scene, then adapt it to your architecture.