HN Explorer

Show HN: Reladraw – A diagram language where you decide where to place things (github.com)

1 points by jpwalsh234 ↗ HN
I love making diagrams to help understand, plan, etc. However, the options are (A) auto-placement languages like Mermaid or Graphviz (which don't let me decide how the diagram looks), or (B) software like Draw.io which are powerful but are very time consuming (and inefficient for agents to manipulate).

I wanted to have the benefits of both, where you can define a diagram in a diagram language, but also retain a high degree of control over what the diagram looks like.

I also wanted this to work well for humans and agents.

On the Github link, there's a playground where you can try it out without installation. There's also instructions for a simple npm install and for installing a skill you can use with Claude or other agents.

103 comments

[ 5.8 ms ] story [ 151 ms ] thread
v9v
Great! Reminds me of Pikchr a bit https://pikchr.org/home/doc/trunk/homepage.md
[dead] jpwalsh234
[dead]
gandreani
Can you share an example?

I've been playing with pikchr quite a bit and it has containers and you can specify links relative to the container. I can picture (pun not intended) your counter-example

jpwalsh234
Great question, I had to noodle that one over a bit, but I think it helped me clarify that difference between pikchr and reladraw. My container example was a poor one, and you are right that pikchr can handle adding elements to a container without fiddling.

My main objection to pikchr is that it is turtle graphics plus coordinate offsets, which to me feels like the wrong tool when I want to say "I have A to the left, and B, C, and D all right of A". I don't want to have to translate that to turtle graphic movements like saying "there's a group, draw B, move down some amount, place C, move down again, place D".

Similarly, if I'm thinking at the level of abstraction of nodes and edges and relative positions, it feels awkward to say something like this in pikchr (where the 0.2 is a guess to fiddle with):

  arrow from Web.s down 0.2 then right until even with DB.s then to DB.s
Rather than saying in reladraw:

  edge web -> db   from: bottom  to: bottom
I think it's less a matter of "reladraw can do it, but pikchr cannot". It's more like, "both can get to the same destination, but how you get there is a matter of taste and how you express your intent".

For example in pikchr:

  A: box "A" fit
  G: [
    down
    B: box "B" fit
    move 0.1
    C: box "C" fit
    move 0.1
    D: box "D" fit
    move 0.1
    E: box "E" fit
  ] with .w at A.e+(0.5,0)
  arrow from A to G.B chop
  arrow from A to G.C chop
  arrow from A to G.D chop
  arrow from A to G.E chop
To me, it's not as clear that your intent is that you want several nodes right of A. However, in reladraw, it's clearer to me that the intent is "these things are right of A":

  node a "A"
  node b "B"  right of a
  node c "C"  right of a
  node d "D"  right of a
  node e "E"  right of a
  edge a -> b
  edge a -> c
  edge a -> d
  edge a -> e
However, that's a subjective taste thing and I could see some people liking the pikchr approach.
gandreani
This is a great example! Thank you

I think you're right that it's a matter of taste and that the intent is better represented by reladraw.

If I can point some personal downsides of pikchr is that there's no loops and when using macros you can't use parameters to create object labels.

For example, Triangle$1: line...

Just some thoughts in case you're looking for future inspiration for the language

jpwalsh234
Oh interesting! I plan to add custom attributes, functions, variables. I was also thinking about macros and will add your parameters for object labels in as another idea. Thanks :)
tetris11
I like it. I have too many issues with Mermaid
jpwalsh234
Thanks! I really like Mermaid, but if the diagram gets too complicated, it draws it how it wants and I end up reaching for Draw.io, which is also awesome, but can take a lot of time.
monster_truck
This genuinely fucks. Thank you
jpwalsh234
Glad to hear it :) If you find that you want Reladraw to do something that it can't, let me know! I keep uncovering features by looking at actual Draw.io diagrams I've made and seeing if Reladraw can do it.
Jailbird
(since you ask...) Edges drawn with right angles would be a nice option.
jpwalsh234
Great idea! Adding to the todo list.
jpwalsh234
Updated! Edges can now have right angles (sharp or rounded). And, I added in more edge customization, like solid/dashed/dotted and thickness.
monster_truck
o7 will do, and if I cook anything up I think you might appreciate I'll try and yeet over a nice PR
lastscattering
This is basically tikz's positioning library (right=of, below left=of) without having to touch LaTeX. With tikz it was never the nodes that hurt me, it was the edges. Once two edges want the same side of a box it gets ugly fast. Does the resolver do any routing, or is from:/to: all you get? And what happens with conflicting statements, does the first one win or do you get an error?
jpwalsh234
Appreciate the comment and questions!

Does the resolver do any routing? It doesn't auto-route around obstacles. But, if nodes A, B, and C all have edges going to the left side of D, they share that side and space themselves apart so they don't cross. If the side is too short, they'll bow out to make space for each other, so you don't have to manually fiddle. You can also give routing instructions like "these edges pass between these two nodes on their way to D".

Conflicting statements? Statements that can all hold will all apply. Right of one node and below another is okay. Or, "right of A and B and C" will clear whichever sticks out furthest. If they all can't hold, you'll get an error naming the clashing statements (e.g., something both left and right of A). Nothing silently wins.

patriciobcs
I was looking for something like this. I wish it had different themes, the will prob be the best improvement.
jpwalsh234
Great idea! So, right now it defaults to this sorta "dark" theme, and the only option you'd have is to change the diagram background color or define styles. I'll make defining some preset themes a priority!
jpwalsh234
Just pushed an update to add a basket of themes, including light and dark themes.
aktenlage
That is damn interesting. When I made copilot write a script that creates a .dot diagram, I found it funny that it had the same problems with placement that I have when doing it manually.
jpwalsh234
Thanks very much! Yea, with .dot, the layout engine decides where things go. So, the agent doesn't know what the result looks like, leading to render, look, fiddle loops. And, depending on how much you care about layout, .dot might not give you enough knobs to turn to make it look like what you want.

The idea with Reladraw is that a human or agent could just state "I want this node to the right of this other one", rather than have a layout engine decide. Hopefully less fiddling for agents!

kinduff
I love it, and I wish it was part of Mermaid. I've always struggled with the presentation and agents tend to hack or just straight use SVG lol
light_hue_1
I wish this just implement tikz without latex. I've yet to see a better drawing library that is both simple and has the depth to build the most complicated things.
jpwalsh234
tikz looks super powerful. Reladraw is opting for a narrower job - making diagrams with boxes, groups, arrows, where you can say relative positions and let Reladraw save you extra work.
ciefa
Huh, can you read my mind?! :D

This is super cool. I love diagrams, charts, etc. and use them a lot. Both privately and for work.

Definitely going to make use of this, I didn't know how much I wanted something like this until right now hahaha.

recroad
Seems a little buggy, I added this line:

edge parser -> renderer "test edge" from: left to: right

and it wasn't smart enough to make a curved arrow

jpwalsh234
Genuine bug! Good find. I'll look into a fix.
jpwalsh234
Bug is fixed in the playground. Thanks again for catching it!

It gave me some ideas to make routing better, too. For example, maybe you don't want the edge to curve above, but rather below. Or, in more complex examples, maybe you want the edge to curve above one thing and to the right of another.

(will update npm shortly too)

recroad
This is just for me, but I don't think I want to get into the business of specifying placement in that much detail. It would too cumbersome and I'd rather focus on what I want the diagram to convey, rather than how.
HeavyStorm
Mermaid works great for fixed layouts like sequence diagrams and Gantts. For flowcharts, where position is king, it's bad.

I've tried using svg in my MD files but they get unwieldy quite fast. This is a great idea. My first reaction was - but what's if I need something more exact. But reflecting on it, I've realized that this relative positioning is probably enough.

jpwalsh234
Yea, it's hard to beat absolute positioning if you want something ultra-custom, but I'm hoping for most flowcharts, mind maps, etc. the relative positioning is enough to get what you want without fiddling too much!
y-curious
Agreed. Next diagram I make I’m taking a photo of a whiteboard and letting AI figure out relative positioning
threecheese
Does this need to be shipped with a renderer? A better question is, are the node layout instructions ultimately being translated into absolute positions?

If so, you could target any number of render backends, keeping the same simple interface for your agent, avoiding the bazillion problems rendering engines face to work well across the ecosystem.

jpwalsh234
Great idea! Yep, the layout instructions are translated into absolute positions. The one gap right now is just that the CLI doesn't give you a way to say "just calculate the positions, stop there, and give me JSON". The logic basically exists to do that, with a minor tweak to the CLI to allow that.

I'll add that to my Reladraw todo list!

wrs
[delayed]
jpwalsh234
That's a very thought-provoking question. Adding placement constraints on top of an automatic layout engine sounds like a challenging problem. You'd have the engine deciding where to place things, but you'd also be nudging things or constraining things.

This might not be what you have in mind, but Graphviz has a `rank` which can be used as a coarse way to influence the shape of the diagram. (I'm assuming you had something more sophisticated in mind though)

Probably easier would be if the relative drawing were its own distinct Mermaid diagram type, but then it would be largely a new language anyway.

einpoklum
If this were implemented in a language with fewer dependencies, it'd be great.
tnspacetime
This seems nice but I’ll need to read the syntax more carefully to see how capable and convenient it is.
jpwalsh234
Definitely! Capability vs convenience is tough! Hope you find it useful.
apinstein
[delayed]
jpwalsh234
It's funny, you articulated it very similar to how I feel! Seems like we need ways to maintain mental models at a high enough level of abstraction when working with agents.

There's a skill in the repo that you can install using `npx skills` to get started with. I'm sure the integration of Reladraw with agents can be made way better, though. It's just a bit... basic/rudimentary right now!

Towaway69
Won’t it be a good idea to stay at the visual level?

Instead of generating visuals from text and then back to text, just communicate visually with your agents.

Something like UML provides a certain granularity to be able to code something usefully in pure visual language. Of course there are other visual programming languages that provide more depth and would probably be better suited.

Point remains that a solution based on constantly mapping better two different representations of the same thing won’t be a long term efficient solution.

tamimio
I tried most of the diagrams out there, the best thing is installing drawio skill and make it generate one for you based on your description.
loveTech
Exactly! I'd like to give it a try as well!
rodmena
interesting. wonder how agents themselves can create something complex. I'll use it for sure. I direct my agents to [Graphviz provider](https://graphviz.rodmena.co.uk/)s these days.
jpwalsh234
That's cool! I'm curious to see how it goes if you try making some super complex :)
Garlef
1. awesome ~ this seems to be in a sweet spot! (yes, mermaid is fine; but often looks bad - esp when visualizing large diagrams)

2. it would be great to have this as a layouting layer for C4

3. which brings me to a suggestion: i think it would make sense to allow for decoupling the topological parts of the language (arrows, groupings, etc) from the layouting concerns (left of, right of, etc)

jpwalsh234
Super interesting. So, you'd have something like "use architecture.dsl" (to "load" the C4 model definitions), and then begin to specify layout?
Garlef
Yes tust would be one way. But maybe a suite plungins that allows other renerers to consume .rel files might make for a better ecosystem.

To explain the use case: One advantage would be: maintain model (and views) in C4, provide layout on top.

We recently generated a big C4 model of the whole company. Good and informative since you can click through it! But it doesn't look nice and doesn't tell a coherent picture visually.

altcognito
This is an area I think I've really enjoyed AI coding: DSLs are pretty fun to make and you can get pretty creative. Bravo on this
tombert
You stole my planned project for next weekend! I was actually planning on doing something very similar to this.

I'm glad you beat me to this; I think what you made is likely better than what I would have produced.

jpwalsh234
Thanks very much! If you have ideas or feature requests, let me know!
lampcord
Always struggle with Graphviz tweaking my carefully planned positions. Explicit control here looks like a godsend.
jpwalsh234
Yea, I felt the same. I started with Graphviz (dot language) and had fun playing with it, but ended up always back to something like Draw.io, because I couldn't get things positioned how I wanted.
squidlib
OP, is this something I could use when someone is explaining their architecture and this simply can interpret their words into a diagram?
jpwalsh234
Not by itself, but an agent using Reladraw could. The real smarts would be the agent, and Reladraw just gives it a language and tool to express itself clearly and efficiently.

You could take someone's explanation of their architecture, give it to an agent, and ask it to render it as a diagram using Graphviz, Mermaid, Draw.io, etc. The problem is that some of those don't give the agent control over what the diagram looks like (Graphviz, Mermaid) and others are inefficient and fiddly for an agent to manipulate (Draw.io). Reladraw aims to be easy for an agent (or human) to edit (like Mermaid) but have the expressiveness and positioning like you'd be able to achieve with a carefully crafted Draw.io diagram.

boblehest
The README looks LLM generated. Sorry, but that's where my interaction stops
jpwalsh234
Appreciate the feedback. I gave the README a rewrite.
Kwpolska
Now do the rest of the codebase.
faeyanpiraat
Why put so much effort (checked your blog as well) into hating the new reality ?
ncr100
I also want to know, and liken the pop fervor seen from some as religious in origin.

https://news.ycombinator.com/item?id=49878739 (my analogy.)

I'm guessing we're seeing actual religions appear, human effort potentially being blessed and machine being the work of Satan. It feels like those times are emerging, to me where people are inventing new religions out of fear of meaninglessness.

Strange times indeed.

oa335
why?
Kwpolska
Why would you consider a project which appears to be fully coded by Claude worthy of a Show HN post?
ncr100
Why does Claude output being shown to humans mandate it be rewritten before before consumption? What school of thought is that from?

Snark humor: We are not in The Name Of The Rose and this coffee is not Aristotle's forbidden second volume of Poetics which is antithetical to the teachings of Christ and is deserving to being hidden in a labyrinth by Benedictine monks.

oa335
because it is useful and interesting. why should they rewrite the project without LLM input?
tamimio
Add a way to convert drawio into this or generate it from drawio