GitHub – reladraw/reladraw · GitHub

A textual content language for diagrams the place you say the place issues go.

Try it in your browser → — edit the supply on the left, watch the structure re-solve on the fitting. Nothing to put in.

A diagram drawn by hand in draw.io:

And the identical diagram written down in reladraw and rendered from the textual content — examples/arch.reladraw, 44 statements, no coordinates wherever in it:

Every distance within the second image was labored out from statements like above-left of cluster.hub and between cluster.desktop1 and cluster.laptop1. Nothing selected the association; the file states it.

Mermaid, Graphviz and D2 have you ever declare entities and connections, after which place every little thing for you. That is a superpower, and for many diagrams it’s the proper one. It stops being the fitting one as quickly as you might have a selected image in thoughts and care the place issues go. Say you’re actively constructing your understanding of a system by diagramming it, and also you need some module over to the fitting with its connections positioned simply so: the auto-layout languages don’t have any method to say it.

On the opposite finish of the spectrum are the absolute-positioning instruments — draw.io, Excalidraw, Figma. They provide you with complete management of placement, at the price of making each edit to a posh diagram sluggish hand-work. And it’s sluggish for a human however costly for an agent, which has to work the image out from the coordinates earlier than it might resolve which of them to vary.

reladraw goals on the center. Every place is acknowledged relative to one thing else, and nothing within the file is a coordinate:

node app "Web app"
node app.ui  "Interface"
node app.api "API"  under app.ui

node retailer "Database"  proper of app  stage with app

edge app.api -> retailer  "queries"  from: proper  to: left

Nothing is nested, so no line will depend on one other line’s place or indentation.

The draft is in SYNTAX.md, with a labored instance in examples/.

The frequent case is just not drawing a diagram, it’s altering one. Ask for the auth service to maneuver left and a queue to go behind it. With pixel coordinates, an agent has to rebuild the image from the numbers earlier than it might work out which numbers to vary. With auto-layout there may be nothing to learn in any respect, as a result of the association was by no means written down — it might solely reword the supply and re-render. With acknowledged placement the association is within the file as sentences, and altering the image is altering the sentence that claims the place the factor goes.

Writing has the identical form. An agent emitting Mermaid is guessing at a structure that an algorithm settles later, and its solely method to discover out is to render and look — a spherical journey that comes again as an image fairly than as a listing of what’s unsuitable.

Intent is confirmable, outcomes are usually not, and the distinction is value being exact about. An agent can re-read its personal file and see that the database is beneath the API and all 4 machines hold off the sync hub. It can not see that two clusters anchored to various things now overlap, {that a} textual content overflowed its node, or that an edge crosses 4 others — these are resolved from the statements fairly than acknowledged, in order that they want the diagnostics within the scope part under.

reladraw is simply too new to be in any mannequin’s coaching information, so an agent must be advised the language earlier than it might write it. This repository ships an agent skill that does precisely that — the syntax, when to succeed in for the language, and what re-reading its personal supply can and can’t verify.

npx expertise add reladraw/reladraw -g

That installs it for whichever agent you employ — Claude Code, Codex, Cursor, Copilot and others — every into its personal expertise listing. Drop the -g to put in it into the present mission as a substitute.

To set up it for one agent fairly than all of them, identify it with -a:

npx expertise add reladraw/reladraw -g -a claude-code

Re-run whichever command you used after a launch that modifications the syntax. The talent is a duplicate taken at set up time, not a dwell hyperlink, so nothing refreshes it by itself.

It is plain Markdown with the syntax reference beside it, so it’s value studying no matter you employ, and copying the listing by hand works simply as properly.

Version 0.4.0. Early, however it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line software that takes a textual content file and writes a standalone SVG. The comparability on the prime of this web page is that pipeline run on examples/arch.reladraw. What remains to be visibly off there may be typography, not placement.

npm set up -g reladraw
reladraw diagram.reladraw -o diagram.svg

Or from a clone, which additionally will get you the examples:

npm set up && npm run construct
node dist/cli.js examples/arch.reladraw -o out.svg

Not constructed but, roughly within the order they’re missed:

• The diagnostics report. The scope part under says what it’s for. Today the software both renders or fails; it is not going to inform you what’s unsuitable with an image it drew efficiently.
• Edge routing round nodes. An edge will be advised which facet of a node to depart and arrive on, and which hole to run down on the best way. An edge that claims none of that may be a straight line between two facilities, and it’ll lower by no matter stands in the best way.
• More photos. Icons and shapes are closed units drawn from path information contained in the software, so a diagram wanting one that’s not there has nowhere to go.

The language is just not steady. Expect the syntax to vary.

A niche is a minimal distance, by no means an actual one. Say two issues sit facet by facet, then say a 3rd goes between them, and the primary two are pushed aside by precisely what the third wants; delete the third and so they shut again up. That is the step an writer in any other case does by hand — shove issues aside to make room, then drag every little thing again so the diagram is just not stuffed with holes — and no quantity goes stale when a textual content grows.

So the resolver solves a system fairly than strolling a series. Each axis is a set of minimal distances, and the tightest association satisfying all of them is discovered by longest paths: one reply, no search, no association ever tried and rejected. The engine works out distances; which facet of what a factor sits on got here from the file.

That can also be what makes non-overlap reasonably priced, so it holds for each pair of nodes with out anybody writing it down. On its personal “these two should not overlap” is a selection amongst 4 instructions, which is the search this design refuses — however the file has often settled it already: in case your association lets one node journey away from one other and gives no means again, that’s the solely separation it permits. Where the file orders a pair on neither axis, the software names them fairly than guessing; the place it orders them on each, the tie breaks towards the axis of least overlap, which is the smallest motion and the one place the software decides one thing no one wrote.

Nothing is nudged. Each spherical derives the separations the file already implied, provides them as bizarre minimal distances, and solves the entire thing once more from scratch — repairing a solved structure in place is the factor being prevented.

• Parser (completed)
• Deterministic resolver: minimal distances in, tightest association out (completed)
• Static SVG renderer (completed)
• A command-line software: textual content file in, SVG out (completed)
• A placement grammar that may say what an actual diagram wants: a number of placements on one node, one factor between two others, precise side-to-side alignment (completed)
• Nodes that don’t overlap by default, with the separation route derived from the acknowledged association (completed)
• Minimal node-avoiding edge routing
• Machine-readable diagnostics from the solved geometry

Diagnostics are an actual output fairly than a debugging assist. What they can’t do is stand in for the grammar: a verify catches solely what the language genuinely leaves open, and “these should not overlap” guidelines preparations out with out naming one, so it might by no means place something. Everything the supply can not inform you is computable as soon as the geometry is solved, with no picture concerned: overlapping nodes, crossed edges, textual content exceeding its container, something off-canvas, giant useless areas. So the software stories hub overlaps laptop1 and edge auth->db crosses 4 edges, and the repair is written in the identical vocabulary because the supply. An agent working this manner reads a report a few textual content file it wrote and edits that textual content file — no rendering, no imaginative and prescient mannequin, no pixel arithmetic.

A diagnostic by no means repairs a solved structure in place. That is the road the design holds: a checker allowed to nudge nodes is a structure algorithm with a foul search technique, fixing one overlap into the subsequent with no view of the entire. Deriving a constraint the file already implied and fixing the entire system once more is a unique factor, and is how non-overlap works. What is left over — something the supply genuinely doesn’t settle — is reported, naming the assertion that was damaged, and the writer edits the supply. Open, and it decides how far this goes: might a diagnostic describe a repair in phrases, or solely identify the symptom? Describing one means the software has an opinion about structure, which is the auto-layout intuition coming again in by the facet door.

Three design issues resolve how a lot equipment this wants, and the primary outranks the opposite two:

Saying sufficient. The benchmark incorporates preparations the grammar can not specific in any respect, which is why some nodes land within the unsuitable place irrespective of how the file is written. So the work is including statements, not proscribing them. Expressiveness is just not the hazard; the engine selecting an association is.

What the engine is allowed to resolve. Auto-layout is refused, as a result of an image chosen by an algorithm is just not predictable from its supply, and that predictability is your complete level. Working out coordinates from an association the writer acknowledged is a unique factor and is solely the job. The check between them: the engine’s freedom might have an effect on distances and by no means relationships. If a default can change which facet of one thing a node sits on, the language was brief a press release and the software ought to say so fairly than guess.

Overlap and edge routing. Relative placement with default spacing collides as quickly as two clusters develop towards one another. Stating placement after which routing edges afterward with no affect on them reproduces the precise failure that is meant to keep away from, so minimal node-avoiding orthogonal routing belongs within the first model. Routing and diagnostics are enhances, not substitutes: routing fixes what it might, and the diagnostics report what it couldn’t.

Four issues sit close to this, and every solutions a unique a part of the issue.

Archify. Built for brokers to put in writing: an agent emits typed JSON, a validator checks it towards a schema and lints the structure, and it compiles deterministically to a handsome, self-contained HTML file, with stepped playback and nodes pinned to git-verified supply traces. Its positioning is grid or free coordinates, although — auto-arrangement on one facet, absolute pixels on the opposite — and a JSON template says nothing about the place the image will find yourself, so the loop remains to be emit, render, look, tweak.

PIC and pikchr. A textual content diagram format with no structure engine, the place placement is acknowledged and deterministic. But it’s turtle graphics — a movable cursor that drops shapes and steps alongside — so a diagram is a sequence of pen actions fairly than a set of acknowledged relationships between named issues. There is not any group that reflows when a member is added.

Graphviz rank and cluster. Constraints on an auto-layout engine fairly than a alternative for one, so output stays emergent and unpredictable from the supply.

Structurizr. Has actual guide structure, however is sure to the C4 mannequin, which makes it a modeling notation with a renderer connected fairly than a common placement language.

Apache-2.0. This is a reusable primitive the place adoption is the worth, so proscribing industrial use would defeat the aim. See LICENSE.

The license covers the code, not the identify: it grants no rights to make use of “reladraw”, the mission brand, or the mission’s different marks. Forks are welcome and will carry a unique identify. See NOTICE.

Issues are needed — particularly a diagram you tried to put in writing and couldn’t. Pull requests are learn however not merged but, for a purpose defined in CONTRIBUTING.md.