Show HN: Diagram as code tool with draggable customizations

266•RohanAdwankar•3mo ago

In the past I've used declarative diagram generation tools like Mermaid.js a lot for quickly drawing up things but for presentations or deliverables I find that I have to then move the generated diagrams over to a tool like Lucidchart which allows full control of the organization and customization.

Therefore I am now working on this to combine the benefits of both into just one tool which can do both functions.

The project is certainly in the early stages but if you find yourself making architecture diagrams I'd love to hear your thoughts on the idea or even a Github issue for a feature request!

One of the workflows I'm targeting is when an AI generates the first draft of the diagram (all the LLMs know .mmd syntax) and then the user can then customize it to their liking which I think can drastically speed up making complex diagrams!

Comments

vanilla•3mo ago

This looks like a very promising project, I have been looking for exactly this.

One feature I would love to see a declarative diagramming solution would support is a hover pop-up with more information or nested diagrams.

RohanAdwankar•3mo ago

Thanks! I think that sounds interesting, to make sure I'm understanding your use case would these pop ups be for your own use or for other people? For example would you want to send a link to someone else on your team and then the link shows the diagram with popups and nesting? Or would it be sufficient to send over the .mmd files and then the other person can use the cli to open the web interface which supports the popups and nesting. I imagine I could add the latter one quickly but for the former I would either add an easy way for users to self serve like with ngrok or some cloud solution. Or alternatively I could add some way to export the diagram just as a standalone HTML file in which case that could be sent and support the popups and hovering without the person you're sending it to having to have the CLI installed.

vanilla•3mo ago

ilograph [0] has these features. I think it should be possible with SVG only. The main use-case would be for documentation sites.

[0] https://www.ilograph.com/features.html

RohanAdwankar•3mo ago

Thanks for sharing I'll look into this. The animations do look great!

anorak27•3mo ago

Wonderful project.

There's also mermaidjs to excalidraw https://github.com/excalidraw/mermaid-to-excalidraw

RohanAdwankar•3mo ago

This seems cool! Thanks for sharing.

huydotnet•3mo ago

Wonderful! I have been wanting something like this for a really long time!

RohanAdwankar•3mo ago

Thanks!

gurjeet•3mo ago

Great job on the releasing the project; it definitely solves a need of being able to use declarative syntax for defining the relationships, and then customizing the layout which the regular layout generators can't do.

Project's Cargo.toml file says code is licensed under MIT license, but there's no license file in the repository, so Github doesn't show what the project is licensed under. Please add the license file so that people see it without having to dig through the code/configuration to determine that.

gurjeet•3mo ago

If you wish to increase the adoption the tool, do consider hosting it to make it easy for people to use it. I see that it's heavily dependent on server-side code, so the cheap/free static hosting wouldn't be an option.

RohanAdwankar•3mo ago

That makes sense I will eventually get to that!

RohanAdwankar•3mo ago

Thanks for catching that! Just added the license file.

plmpsu•3mo ago

I really wish PlantUML would just solve this jarring problem.

dixtel•3mo ago

Very cool idea, this is exactly what I'm missing from mermaid. Thanks for sharing this!

dboreham•3mo ago

Thank you.

hamburglar•3mo ago

Just FYI your chosen example causes a little confusion in the context of “code tool” because I immediately thought, “is this thing an attempt at some kind of weird visual programming tool which is giving me the choice of Go, Python, and Rust? WTF?” But then I realized that was just sample data.

RohanAdwankar•3mo ago

that would be pretty funny. A visual programming tool for polyglot microservice architectures XD

jtwaleson•3mo ago

I've seen worse ideas ;)

eagleinparadise•3mo ago

This is awesome. I was looking for exactly this last week. A tool I could prompt AI to come up with an architecture and then be able to pick up manually, but visually not editing the code.

Being able to express a workflow or diagram and then have AI implement would be awesome to have a tight loop.

RohanAdwankar•3mo ago

Great to hear! Absolutely this is the goal.

zmmmmm•3mo ago

It's definitely much needed.

I use PlantUML for most diagramming but for anything with more than about 5 components in it I'm spending 20-30% of my time desperately trying to tweak the layout with hints.

It's an interesting approach to embed comments and then build that into the layout engine. I've always thought it would solve a lot of my issues if I could just lock the coordinates for certain components and then let the layout engine do the rest with those as hard constraints. This looks like something similar to that approach.

I really want this because the alternative is to spill over to completely manually maintained diagrams using GUI tools which then can't be easily integrated with source control - I want the same commit that changes the code to also change the architecture diagram for that code. Then it is part of code review and integrates to the whole process well.

Anduia•3mo ago

I use PlantUML because it renders in GitLab's markdown, including wikis, MD docs and even PR comments. However, I have to use Mermaid for projects hosted on GitHub.

The hassle of tweaking the layout in puml, such as pairing elements with an invisible connections and groups, adding or removing dashes from the arrows in class diagrams... is gone because Mermaid is simply inferior in that sense.

Mermaid always feels like it's in beta and I don't understand why GitHub ignores the request to support puml (1). It seems that adoption of diagrams as code is tied to what is supported by major vendors and they don't care enough. Or maybe it is because mermaidchart made an official vscode plugin, who knows.

While I agree that improvements are needed, I'm not convinced that creating a third standard is the answer. What I would like is to be able to assign weights to my elements and let the renderer do the work (not set x and y coordinates like in oxdraw).

[1] https://github.com/orgs/community/discussions/10111

zmmmmm•3mo ago

Oh yes I'm completely with you on wishing Github would support PlantUML. It's almost trivial implementation wise, it's highly embeddable.

It's precisely because I do like it that I want it to scale up better to more complex diagrams. I basically can't push it forward as a universal standard in my org because it fails above a certain complexity threshold and I really can't push for teaching everybody a thousand ways to tweak the diagrams to coax it into doing the right thing (and even then, one small change and it may completely rearrange the output).

monkeycantype•3mo ago

Hello Rohan. This is really great. If you are able to include parameters to expose the intermediate data as inputs and outputs, so that this can be run to a step in the process and output the data, or run from a step with pre-prepared data. It would mean that other people could build on what you've done to create other diagrams and renderings.

RohanAdwankar•3mo ago

Hi thanks! I'm not sure I fully understand what you mean by intermediate data? Would this be the location data computed for the different components?

halostatue•3mo ago

I've made a private MacPorts port[1]; if I find that I use it frequently enough, I might contribute it to the main MacPorts port repo[2].

One thing that's missing from my perspective (and this is probably true for Homebrew packaging as well, but I don't do that) is Git tags / GitHub releases associated with your Cargo releases.

I can work around it for now by using an explicit release (`9ccd9bf53f9a309ccda42b5c17e9c1056493fb90` is what I'm assuming was your 0.1.0 release point).

I've also assumed that npm10 is sufficient (which currently installs node22 on MacPorts).

[1] https://github.com/halostatue/ports

[2] https://github.com/macports/macports-ports

[3] https://github.com/halostatue/ports/commit/e7331a7fcae362b0d...

RohanAdwankar•3mo ago

Thankyou!

chrisweekly•3mo ago

> npm10 is sufficient (which currently installs node22 on MacPorts)

Wait, no, node22 comes with npm10, not the other way around.

halostatue•3mo ago

MacPorts separates `node` and `npm` packages like many package managers do:

    npm10 @10.9.3 (devel)
    
    Description:          npm is a package manager for node. You can use it to install and publish your node programs. It manages dependencies and does other cool stuff.
    Homepage:             https://www.npmjs.com/
    
    Library Dependencies: nodejs22
    Conflicts with:       npm3, npm4, npm5, npm6, npm7, npm8, npm9, npm11
    Platforms:            any
    License:              MIT
    Policy: openmaintainer

The Portfile that I created specifies that if `npm` is present in $PATH (which isn't the user's $PATH because MacPorts uses `sudo`) then it should be used and assumed correct; otherwise, it says that the `npm10` port must be installed (because the instructions for oxdraw indicate that one must run `npm install && npm build`).

chrisweekly•3mo ago

Thanks, that makes sense.

metmac•3mo ago

I really wish Mermaid would just ratify a layout spec. Make it optional. Use it. Great. Don’t use it. The layout engine does its thing.

benblu•3mo ago

Thank you! Very cool.

I don't see a button for it (on mobile currently, and will check thoroughly at my computer) -- is there a button to add a node?

Another feature I've always craved for code diagramming is "collapse downstream nodes" -- though it might be outside of your scope (and mermaids?).

RohanAdwankar•3mo ago

Hi as of now I haven't added that feature so the current way would be to edit the .mmd text. However I think you are right that would be a good feature to add. For collapsing downstream nodes I think it would make sense with the request the someone else made in this thread for animations. From what I see it should certainly be possible to implement at some point!

liqilin1567•3mo ago

Great project, I've been generating diagrams with llm for a while, and I often struggle to refine layout through the model.

But now I can interactively make changes to the diagram with this, it's very productive.

RohanAdwankar•3mo ago

Thank you! Happy to hear that!

newusertoday•3mo ago

i generally use plantuml in emacs for generating diagrams from text but it does not allows for drag and drop editing. This looks cool.

lmeyerov•3mo ago

Is this embeddable, eg, a react component that can be hooked into?

The lack of this has been a sticking point making us lean to dropping mermaid, so very cool to see!

RohanAdwankar•3mo ago

Oh thanks, that's a good idea I'll make a issue on the github for that and get to it eventually!

dackdel•3mo ago

isint tldraw an alternative to this

RohanAdwankar•3mo ago

I can look into this further but at a glance I don't see something for declarative diagramming syntax. I will say the name is fantastic! One of the great things about making this thread for me was learning about all the different tools people are using!

parentheses•3mo ago

This looks really cool! Next diagram is getting this treatment!

RohanAdwankar•3mo ago

Thanks, let me know how it goes! There's certainly lots of improvements to be made to the layout engine and polishing for the UI so happy to incorporate any feedback!

misiek08•3mo ago

It’s like dot on steroids? Variables and cleaner syntax, but similar premises?

https://graphviz.org/doc/info/lang.html

RohanAdwankar•3mo ago

For the syntax I aim to support mermaid's syntax and any modifications the tool makes are saved as comments so that the files remain backwards compatible with the original mermaid engine!

sandGorgon•3mo ago

so mermaidjs has the concept of layout engines - https://www.npmjs.com/package/@mermaid-js/layout-elk

have you considered implementing your algorithm as a (better) auto-layout engine for mermaidjs ?

RohanAdwankar•3mo ago

Thanks for the comment! I will look into this since I certainly think the ideal scenario would be the core mermaid project supporting customizations in their engine. I imagine that before that I would have to refine the project further after which it would be interesting to see if they would be open to supporting it!

rapnie•3mo ago

Great project! You chose to base on Mermaid.js and that is indeed the most popular declarative diagramming library right now. A more versatile declarative diagramming approach is provided by the D2 Language [0], which may be interesting to check when it comes to supporting more complex diagram types.

[0] https://d2lang.com/

malnourish•3mo ago

D2 is better, but it's not supported by GitHub. Go where your users are.

SOLAR_FIELDS•3mo ago

I’ve long had the stance that mermaids killer feature is that GitHub supports it natively. Ultimately for engineers having rendering at the place where they do the vast majority of their work is huge.

The actual drawing engine sucks compared to something like Graphviz. Works fine up until a certain number of nodes but completely falls apart after that

verdverm•3mo ago

Render an image and put it in the repo, in this way github supports all sorts of tools.

Do you want to risk that your diagram changes outside of your control? (i.e. GitHub changes a mermaid version)

RohanAdwankar•3mo ago

Yes that's essentially my thoughts though perhaps a later feature would be to support the tool customizing d2 files as well! I also think another part about starting with supporting mermaid syntax is that the AI coding agents seem to emphasize mermaid in particular [1] so if they are writing in that syntax anyways I feel it will be even more the norm.

[1] https://cursor.com/docs/configuration/tools/mermaid-diagrams

RohanAdwankar•3mo ago

Thanks for sharing. One of the very fun parts of posting this for me was seeing how much bigger this niche was than I thought haha. D2 seems great and super featureful!

jasonm23•3mo ago

Thank you for making this and open sourcing it, the ecosystem for interactive editing of mermaid / diagrams is all the better thanks to your efforts.

12tilak34•3mo ago

Looking forward to the project for more development !! I have a rust based application where I could integrate this we can collaborate at some point I guess :)

RohanAdwankar•3mo ago

Oh sure collaborating sounds fun, what application are you building?

3abiton•3mo ago

Looks pretty neat, what's the advantage over LLM to mermaid?

RohanAdwankar•3mo ago

The main advantage of this project is it enables customizations of the layout and visual preferences. So using LLMs to write the mermaid code itself still works perfectly fine the mermaid code can then directly be passed in as input and then edited with this tool.

hk1337•3mo ago

I might be missing something but it seems to only be able to edit and work with existing mmd and svg files?

If I do "touch flow.mmd" then run oxdraw to edit the file, it doesn't give me an option to initialize it as a new diagram.

RohanAdwankar•3mo ago

hi this true! i personally typically write my diagram or add nodes in a text editor prior to customizing but I do realize that many would prefer to be able to do everything in the gui so I will start adding features to add nodes and initialize the diagram in the gui!

devsanghvi03•3mo ago

tbh it was very much needed , thanks for this .

We Mourn Our Craft

Speed up responses with fast mode

Hoot: Scheme on WebAssembly

U.S. Jobs Disappear at Fastest January Pace Since Great Recession

OpenCiv3: Open-source, cross-platform reimagining of Civilization III

Stories from 25 Years of Software Development

Al Lowe on model trains, funny deaths and working with Disney

The AI boom is causing shortages everywhere else

The Waymo World Model

Reinforcement Learning from Human Feedback

Start all of your commands with a comma (2009)

Vocal Guide – belt sing without killing yourself

France's homegrown open source online office suite

Coding agents have replaced every framework I used

Selection Rather Than Prediction

A Fresh Look at IBM 3270 Information Display System

72M Points of Interest

Unseen Footage of Atari Battlezone Arcade Cabinet Production

Where did all the starships go?

Software factories and the agentic moment

Show HN: Look Ma, No Linux: Shell, App Installer, Vi, Cc on ESP32-S3 / BreezyBox

Learning from context is harder than we thought

Monty: A minimal, secure Python interpreter written in Rust for use by AI

Show HN: Kappal – CLI to Run Docker Compose YML on Kubernetes for Local Dev

Making geo joins faster with H3 indexes

Ga68, a GNU Algol 68 Compiler

Hackers (1995) Animated Experience

Sheldon Brown's Bicycle Technical Info

An Update on Heroku

Show HN: If you lose your memory, how to regain access to your computer?

We Mourn Our Craft

Speed up responses with fast mode

Hoot: Scheme on WebAssembly

U.S. Jobs Disappear at Fastest January Pace Since Great Recession

OpenCiv3: Open-source, cross-platform reimagining of Civilization III

Stories from 25 Years of Software Development

Al Lowe on model trains, funny deaths and working with Disney

The AI boom is causing shortages everywhere else

The Waymo World Model

Reinforcement Learning from Human Feedback

Start all of your commands with a comma (2009)

Vocal Guide – belt sing without killing yourself

France's homegrown open source online office suite

Coding agents have replaced every framework I used

Selection Rather Than Prediction

A Fresh Look at IBM 3270 Information Display System

72M Points of Interest

Unseen Footage of Atari Battlezone Arcade Cabinet Production

Where did all the starships go?

Software factories and the agentic moment

Show HN: Look Ma, No Linux: Shell, App Installer, Vi, Cc on ESP32-S3 / BreezyBox

Learning from context is harder than we thought

Monty: A minimal, secure Python interpreter written in Rust for use by AI

Show HN: Kappal – CLI to Run Docker Compose YML on Kubernetes for Local Dev

Making geo joins faster with H3 indexes

Ga68, a GNU Algol 68 Compiler

Hackers (1995) Animated Experience

Sheldon Brown's Bicycle Technical Info

An Update on Heroku

Show HN: If you lose your memory, how to regain access to your computer?

Show HN: Diagram as code tool with draggable customizations

Comments