reladraw: Een teksttaal voor diagrammen waarbij je bepaalt waar dingen komen te staan

De kloof in diagram-tools

Er bestaat momenteel een kloof tussen twee soorten tools voor het maken van diagrammen:

1. Auto-layout talen (zoals Mermaid, Graphviz en D2): Hierbij declareer je entiteiten en verbindingen, waarna de tool de plaatsing voor je regelt. Dit is krachtig en voor de meeste diagrammen de juiste aanpak. Echter, zodra je een specifiek beeld in je hoofd hebt en controle wilt over waar dingen staan, schieten deze talen tekort. Er is geen manier om te zeggen dat een specifiek module rechts moet staan met verbindingen op een precieze manier geplaatst.
2. Absolute positioneringstools (zoals draw.io, Excalidraw, Figma): Deze geven volledige controle over de plaatsing, maar maken elke wijziging in een complex diagram tijdrovend handwerk. Dit is niet alleen traag voor mensen, maar ook kostbaar voor AI-agents, die het beeld eerst moeten herleiden uit coördinaten voordat ze kunnen bepalen wat er gewijzigd moet worden.

Reladraw bevindt zich in het midden. Elke positie wordt relatief aan iets anders bepaald, en er worden geen vaste coördinaten gebruikt.

Voorbeeld van syntax

node app "Web app"
node app.ui  "Interface"
node app.api "API"  below app.ui
node store "Database"  right of app  level with app
edge app.api -> store  "queries"  from: right  to: left

In dit systeem is niets genest, waardoor geen enkele regel afhankelijk is van de positie of inspringing van een andere regel.

Waarom een AI-agent dit nodig heeft

De meest voorkomende use-case is niet het tekenen van een diagram, maar het wijzigen ervan. Bij het gebruik van pixelcoördinaten moet een agent het beeld reconstrueren uit getallen voordat hij kan bepalen welke getallen gewijzigd moeten worden. Bij auto-layout is er niets te lezen, omdat de specifieke schikking nooit is vastgelegd; de agent kan alleen de brontekst aanpassen en opnieuw renderen.

Bij relatieve plaatsing staat de schikking in het bestand als zinnen. Het wijzigen van het beeld betekent simpelweg het wijzigen van de zin die bepaalt waar een object staat.

Dit maakt intenties bevestigbaar. Een agent kan zijn eigen bestand herlezen en zien dat de database onder de API staat. Wat een agent niet kan zien, zijn zaken die voortvloeien uit de berekeningen (zoals overlappende clusters of tekst die buiten een node valt). Hiervoor zijn diagnostische rapporten nodig.

Gebruik met een AI-agent

Omdat reladraw te nieuw is voor de trainingsdata van de meeste modellen, moet een agent de taal aangeleerd worden. De repository bevat een "agent skill" die de syntax en de gebruiksregels uitlegt.

Installatie

Om de skill toe te voegen voor de agent die je gebruikt (zoals Claude Code, Codex, Cursor of Copilot), gebruik je: npx skills add reladraw/reladraw -g

Om het alleen voor één specifieke agent te installeren (bijv. Claude Code): npx skills add reladraw/reladraw -g -a claude-code

Status van het project

Versie 0.5.0 Het project is in een vroeg stadium, maar functioneel. Het bevat een parser, resolver en SVG-renderer geschreven in TypeScript zonder runtime-afhankelijkheden, inclusief een command-line tool.

Installatie en gebruik via CLI

npm install -g reladraw
reladraw diagram.reladraw -o diagram.svg

Of via een clone:

npm install && npm run build
node dist/cli.js examples/arch.reladraw -o out.svg

Nog te ontwikkelen functies

• Diagnostisch rapport: Een tool die melding maakt van wat er mis is met een succesvol getekend beeld (bijv. overlappende nodes).
• Edge routing rond nodes: Momenteel zijn verbindingen rechte lijnen. Toekomstige versies moeten verbindingen kunnen laten lopen langs de zijkanten van nodes.
• Meer visuele elementen: Uitbreiding van de set iconen en vormen.
• Stabiliteit: De taal is nog niet stabiel; verwacht wijzigingen in de syntax.

Hoe het werkt

Het concept van de 'gap'

Een "gap" is een minimale afstand, geen exacte afstand. Als twee objecten naast elkaar staan en er wordt een derde tussen geplaatst, worden de eerste twee precies genoeg uit elkaar geduwd om ruimte te maken. Verwijder je het derde object, dan sluiten de anderen weer naar elkaar toe.

De Resolver

De resolver lost een systeem op in plaats van een keten te volgen. Elke as is een set van minimale afstanden. De meest compacte schikking die aan alle eisen voldoet, wordt gevonden via "longest paths". Dit resulteert in één definitief antwoord zonder dat er verschillende arrangementen geprobeerd en afgewezen hoeven te worden.

Overlappingen worden voorkomen doordat de tool de richting van scheiding afleidt uit de beschreven schikking. Als het bestand geen volgorde bepaalt op een bepaalde as, geeft de tool dit aan in plaats van te gokken.

Scope voor de eerste versie

Voltooid

• Parser.
• Deterministische resolver (minimale afstanden in, compactste schikking uit).
• Statische SVG-renderer.
• Command-line tool (tekstbestand in, SVG uit).
• Plaatsingsgrammatica voor reële behoeften (meerdere plaatsingen op één node, objecten tussen anderen, exacte zij-aan-zij uitlijning).
• Standaard voorkoming van overlap.

In ontwikkeling

• Minimaal node-avoiding edge routing.
• Machine-leesbare diagnostiek van de opgeloste geometrie.

Filosofie over diagnostiek

Diagnostiek moet een echt output-product zijn, geen debug-hulpmiddel. Alles wat de brontekst niet expliciet benoemt, is berekenbaar zodra de geometrie is opgelost: overlappende nodes, kruisende edges, tekst die buiten de container valt, etc. Een agent kan zo een rapport lezen over een tekstbestand dat hijzelf heeft geschreven en dit vervolgens aanpassen, zonder dat er een vision-model of pixel-berekeningen aan te pas komen.

Bestaande technieken (Prior Art)

Reladraw onderscheidt zich van de volgende tools:

• Archify: Gebouwd voor agents via typed JSON. Gebruikt echter grid- of vrije coördinaten, waardoor de loop nog steeds bestaat uit: genereren, renderen, kijken en aanpassen.
• PIC en pikchr: Een tekstformaat zonder layout-engine. Het werkt als "turtle graphics" (een cursor die vormen plaatst), waardoor het een sequentie van penbewegingen is in plaats van een set relaties tussen benoemde objecten.
• Graphviz (rank en cluster): Dit zijn beperkingen op een auto-layout engine, waardoor de output emergent en onvoorspelbaar blijft vanuit de bron.
• Structurizr: Biedt handmatige layout, maar is gebonden aan het C4-model, wat het een modelleer-notatie maakt in plaats van een algemene taal voor plaatsing.

Licentie

Het project is gelicentieerd onder Apache-2.0. Dit is een herbruikbare primitieve waarbij adoptie de belangrijkste waarde is; beperkingen op commercieel gebruik zouden dit doel tegenwerken.

Let op: De licentie heeft betrekking op de code, niet op de naam "reladraw", het logo of andere merken.