📐 Architecture diagrams you can diff

There is a kind of engineering work that consists of moving a rectangle three pixels to the left, deciding it was better before, and moving it two pixels back.

Architecture diagrams generate a lot of this work. The boxes are rarely the hard part. The hard part is keeping the picture honest while the system changes. Add a service, reroute a connection, export a slide, and notice that a label now sits inside the database.

I built Sceno on a different premise: the diagram is a document, and the picture is one way to read it.

A diagram you can review

Sceno uses KDL, a text format that is comfortable with nested things. A small diagram looks like this:

diagram title="A small service" layout=auto gap=32 padding=24 {
  shape box api "API" layer=1
  shape cylinder db "Database" layer=2
  edge api -> db
}

You don’t need to find the right toolbar icon to understand what is going on. There is an API, there is a database, and there is a connection between them. Change that relationship and you get a text diff.

That matters even if no AI agent ever touches the file. A diagram in the repository can change in the same commit as the code it describes. “We added a queue between these two services” is easier to review when the diagram change is right there in the same pull request.

The picture still matters, of course. Nobody wants an architecture presentation delivered as curly braces. Sceno renders the source to SVG, PNG, PDF, HTML and slides.

Validate, describe, advise, render

The part I find more interesting is the feedback around the drawing.

A rendered picture tells you what happened. The scene behind it can also tell you where things ended up and how the connections travel. Validation can point at a problem before you open an image. Layout advice can tell you which area is worth a look.

Here is a real Sceno export from the 0.4 release, showing its own workflow. It is generated from a KDL file, not a mockup.

View the KDL that produced this diagram.

The example is deliberately simple. The point is the loop, not a claim that one command knows what every good diagram looks like.

You can ask for several views of the same source:

sceno validate -i architecture.kdl --json
sceno describe -i architecture.kdl --json
sceno advise -i architecture.kdl --json
sceno render -i architecture.kdl -o output/architecture

Each command answers a different question. Is the source valid? What scene does it describe? What might need attention? What does it look like?

That separation is useful for agents. “Make it nicer” is a very large request. A structured finding narrows it down to the next edit. The agent revises the source, runs the checks again, and shows the new result. A human can use the same loop.

What the checks cannot tell you

This is the limit I keep in mind: layout checks cannot decide which parts of your architecture deserve the reader’s attention.

A perfectly aligned drawing of every component often explains less than a diagram with five boxes. A correct arrow says nothing about whether the dependency is a good idea. Sometimes the right fix is deleting half the diagram.

Sceno takes care of the mechanics so that more of the conversation can be about the system. It doesn’t remove the need for that conversation.

If you want to try it, start with one small flow you already understand. Put it in a file. Change one relationship. Read the diff, inspect the scene, export the result. If that saves you from nudging one rectangle back and forth while muttering “nearly”, it has done its job.

This article describes the Sceno 0.4 release. The versioned README has the commands and the format reference.