Hacker News new | past | comments | ask | show | jobs | submit login
Diagram as Code (mingrammer.com)
396 points by delduca on May 12, 2020 | hide | past | favorite | 74 comments

This looks really neat! Is it possible to have embedded diagrams. For example, Gitlab lets you embed a PlantUML[1] diagram in any Markdown or ADoc file using a proxy server. This makes it really easy to write and serve documentation.

Personally, I'm a fan of PlantUML. Having an svg served in a browser that has labels linking directly to the relevant entity (code, resource etc) is a huge plus for new hire onboarding.

1: https://plantuml.com/

I wish plantUML would update it's default theme, I feel like more people would use it if it didn't look ancient.

I personally enjoy the style of it, but it could be described as “retro.”

PlantUML and Mermaid have really been very useful to me!

It feels like I'm missing something with this tool if one's already aware of Mermaid (and PlantUML)

I was hoping this tool would support directionality/sequencing of nodes.

A tool I've used in the past is SequenceDiagram.org for diagraming a sequence of service calls. While a bit old-school, it's good for its purpose.

I've also used Whimsical[0] to model flows and graph-like relationships. It's got the added benefit of allowing multiple users to view and edit the same document. Whimsical is still my favorite tool right now due to flexibility, but it's a closed-source/paid product, so I'm open to alternatives.

[0] https://whimsical.com/

What about mermaid-js? Here's a sequence diagram example: https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJj...

Exactly. PlantUML and Mermaid have really been very useful to me.

For quick sequence diagrams I really like


It's text-based (build on Mermaid if I'm not mistaken) and really easy to work with for simple interactions.

Also because it's purely text-based you can pass around the full context in the URL. This makes it a little awkward to collaborate vs. a true hosted solution, but it also lowers the barrier to entry significantly.

This looks nice. I'll give it a shot on my next sequence diagram.

web sequence diagrams is very good for sequences. https://www.websequencediagrams.com/

Visually Whimsical looks absolutely stunning... Wow

Looks visually pleasing, but I found their more complex diagrams harder to read compared with something more plain.

Slightly different, but there is now an VSCode extension to use draw.io directly in the editor.


If you don't know draw.io, it's an free diagram software that not only has an XML format to save them, but can also be used to save it as a PNG that EMBEDS said XML, so you can edit it again, but display it like a regular image.

The author has made DSL in Python by (ab?)using context managers and the bitshift operator. It's very interesting, and I haven't seen anything quite like it.

Python can lend itself to horrific abuses through shenanigans like this. I sometimes feel that siren call myself, and usually regret it.

So by default I'm pretty skeptical of this kind of thing, but I'm actually on the fence about this one.

Check out Sagemath for an entire Mathematica thing done entirely through overloading.

Yes! A good point of comparison.

(n.b. I have only used SymPy, not Sagemath. I'm assuming they're similar)

I think sympy (and maybe sage) is a bit different because they're (mostly?) overloading operators for their intended purpose -- that is, the "+" operator does semantically add python objects that represent symbolic math.

Sagemath is a big package that includes sympy.

I have been thinking about using this for some diagrams, but whats been on the back of my mind since I heard about it is how to combine it with Terraform, or Troposphere, and have your infrastructure as code also draw the diagrams automatically.

IME diagrams resulting from production code are not helpful - code is full of boilerplate, irrelevant details and is generally made to solve a problem instead of being documentation.

...but if a tool that simplifies configuration or code into a diagramable state exists, i'd like to know :)

I had the exact same thought!

This is cool! I was hoping it would look something like:

‘’’ import diagrams calc_d = diagrams.new_diagram(“calculator_123”)

calc_d.Datum("SuperNumber") class SuperNumber(int): pass

@calc_d.Service(“Calculator”, “takes numbers and operations and operates”) class Calculator(object): @calc_d.Endpoint("Add", calls=["Increment"], main_data={"b": "SuperNumber}) def add(self, a, b: SuperNumber): out = a for i in range(b): calc_d.multi(calls=["Increment"]) out = self.increment(out)

  def increment(self, a):
    return a+1
def integration_test(): calc_d.instantiate("Calculator") calc = Calculator() ... ‘’’

EDIT: Dear dang and YC Hacker News, I would love to create code blocks using surrounding triple quotes..

Indent with 4 spaces at the start of each line for code blocks.

This is annoyingly difficult in a browser.

Just copy the text and use `sed` on your clipboard to transform your text.

On macOS:

    pbpaste | sed 's/^.*$/    &/' | pbcopy

Perhaps it's more readable/writeable with Awk:

    pbpaste | awk '{print "    "$0}' | pbcopy
Although this also seems to do the same thing

    pbpaste | sed 's/^/    &/' | pbcopy

For anyone finding a solution to code blocks... I write these comments from Safari on my iPhone

It seems to be hyperfocused on system architecture diagrams.

There are some other kinds of diagrams would we like to draw that’s not system architecture diagrams, eg:

- algorithms

- decision trees

- UML/ER Diagrams

Mermaid (JS) helps draw quality diagrams quickly - more than system architecture diagrams.

It would have been perfect if the development cycles that went here was used to create Mermaid templates instead.

Unless this also lets us draw more than just system architecture diagrams.

This would have been perfect for you maybe. I find the Diagrams package to be just fine as it is. A tool or library doesn't have to support _every_ bit of functionality in order to be useful.

The focus would make sense to me if, say, it exported to initial terraform templates or something like that.

I’d prefer to avoid text blob artifacts if this was being used at work with plenty of text blobs to babysit already

IMO the end days for TF and YAML engineering are close, at least for new work

It’s all HTTP APIs. Build a web UX and store the state in a DB.

SRE/ops people ...at work just use the methods everyone else does

Unless the company still has hardware, cloud ops/SRE is just making their lives harder to be different

> It’s all HTTP APIs. Build a web UX and store the state in a DB.

Please no. Don't make running a stateful service a requirement for tooling people need to use when the world is on fire. Or needs to load 40Mb of JS to rebuild a deployment, and works only on Chrome 46.012.2039465. Ops/SRE/DevOps/SysAdmin/SysOps/etc are different, and have optimised things to reduce the amount of dependancies.

What's the alternative you'd recommend?

The explicit, declarative model, using tools that don't need a ton of other things deployed.

Ideally the same tool can be run locally and in CI (with the same invocation commands) so that an Op can run tests locally, and even see the potential diff, before putting it up for review.

The advantage of this approach is you can see a diff, and use standard tooling like git / pr reviews to approve changes in day to day, and when the world is on fire, someone can break the glass and run it locally.

Never underestimate the value of peer review on a change to the infra - there is a reason things like ITIL exist, and we should learn from them.

> The advantage of this approach is you can see a diff, and use standard tooling like git / pr reviews to approve changes in day to day, and when the world is on fire, someone can break the glass and run it locally.

sounds sweet. imagine applying gerrit to infra

> there is a reason things like ITIL exist, and we should learn from them

spot on.

That said, I am unsure if most people here are ITIL aware/certified.

TBH, the primary reason why I am familiar with ITIL is our clients from Accenture days requires certification to win contracts.

> sounds sweet. imagine applying gerrit to infra

Yeah, it is cool - https://opendev.org/ is done that way, as is some of the wikimedia labs infrastructure

I am not certified either - I have just worked in places with ITIL inspired processes, but I can really see a way they can move forward with tools like terraform / pulumi / ansible and git

There is significant value in text blob workflows.

Requiring the definition of everything that makes up your stack to be stored in a format that is not text adds complexity to the disaster recovery process, not to mention mutation, diffing, reviewing, approving, promoting, etc.

For places where a single environment that is updated in place and requires little/no approval to do so, sure. Personally I really like textual definition of infrastructure and configuration, and disagree that it is end days for them.

I'd love if it generated full terraform files with all the required information from the Python code, the rest from sane defaults.

Would also be great to import things with generic names:

    from diagrams.aws.database import RDS as Database
which you could replace at a later point with:

    from diagrams.gcp.database import SQL as Database
And have a provider neutral description that could eventually be compiled into a provider-specific Terraform description just by changing the imports.

Up-voted. That would really make sense and be extremely useful but I don't see anything related to that.

Nice suggestion. The headline appears misleading to me, I like what I see there, but it's really "Diagram as Config" not source code generally.

> "Diagram as Config" not source code generally


As "Diagram as Config" this tool is a great fit but not for "Diagram as Code". There are better alternatives out there.

Why do we need a tool to draw its architecture and we don't have a tool which auto discover the architecture and auto updates it and draw it form here ?

That will shrink the gap between the current architecture and the current diagram that almost always exists

xloudcraft.com auto-generates and updates from live account and gives you info like cost etc.

Looks really.i.ptessive


Stupid mobile keyboards...

I just created a Dockerfile to run: https://github.com/skhaz/diagrams

When I was ~10yrs old, I would play with a program called RPG Maker 2000. It had a really interesting code system where you could click blocks of code and it would bring up a UI for modifying them. It was always simple stuff like if/else, for, switch.. but it merged the simplicity of clicking dropdowns and the like with the complexity of actually seeing the code and learning to read and navigate it. You could also go rogue and write custom code.

I still think that this solution has more life to it and would like to explore that some day.

Slight tangent, but some of the cool tools noted in the comments remind me of some of the amazing things put out by Netflix engineering in recent years, like Vizceral^1 and Flux^2.

1. https://github.com/Netflix/vizceral/wiki

2. https://link.medium.com/LY2vw4Rsr6

(Sorry about the Medium.com link; all I could grab on the spot on phone)

When I first read this I thought this did the inverse of what it actually does. Let you interactively draw out diagrams then it would generate the boilerplate code to achieve that diagram.

I have the exact seem disappointment ;(. As we evolve towards a world were low code will become a part of everday tools, diagram generating code is to me a good answer, at least on a scaffolding level...

If we had a decent diff tool for visual elements, then a whole lot of tools would be practical, including the one you suggest.

Certainly a lot of the building blocks for such a system now exist.

PlantUML and Mermaid have really been very useful to me.

I've got a similar project which takes a diagram of your infrastructure, such as [1] and runs the diagram to build your devops infrastructure [2].

[1]: http://devops-pipeline.com/architecture.tb.png [2]: http://devops-pipeline.com/

Interesting. That was going to be my next question!

I was recently looking for something similar, allowing me to draw network diagrams using text or code. I came across [0] which looks great, but has some rough corners and seems to be abandoned by he author. Does anyone have any other recommendations for more bare-metal oriented topologies?

[0] http://go.drawthe.net/

If you are interested in this kind of thing please check out the blockdiag series of tools (seqdiag, rackdiag, netdiag, etc) I haven't looked back since I started using them other than a workplace that uses lucidchart.


Sent this to a few people at work and it spread pretty quickly. We all love it!

> from diagrams import Diagram

Slightly off-topic, but I wish JavaScript's import syntax was designed to be this way around, for better autocomplete in your editor.

SELECT column FROM table


Why the obsession with product names and logos? Having a Python class for a specific product is not necessary.

...and then people talk about CV-driven development...

I like this a lot - trying to store diagrams that look good, without sticking a visio file into a git repo is something I keep an eye out for.

You may also find value in diagram.codes (I'm the author)

It's focused on non technical users so the syntax will always be very simple (at the cost of flexibility but that's on purpose).

> diagram.codes

looks fascinating. is this closed source?

Can I run this over an API or a local container?

This looks pretty cool and has as nice modern look to it. I can see did a good job with the layout/design too.

If you don't mind sharing (or if anyone knows of any toolkits/libraries): I wanted to try getting at drawing some custom diagrams and was unsure where to begin coding just project. Any know of anything that comes to mind?

This is great. Code needs to replace more drag n drop tools, at the very least to give people options.

Came here half-expecting to see probabilistic programming implemented via Direct Acyclic Graphs (DAGs). This is cool, too, though.

Thanks for sharing! This is really cool.

So, how well does this compare to graphviz? Seems a heck of a lot more verbose.

Graphviz is way more flexible.

this is going to send me down a rabbit hole for a long long time .... there was another thread some months ago about an architecture diagraming tool that reads the code and outputs architecture based on methods.

Why is this better than Mermaid? It works in Markdown, you can version control, and Git(Hub|Lab) displays it automatically.

I'm really curious. Maybe for doing something programmatically, but GraphViz may be better.

> Why is this better than Mermaid?

It isn't. Apples and oranges; Mermaid deals with UML-ish type diagrams whereas 'Diagram as Code' is illustrating cloud system architecture.

> but GraphViz may be better

GraphViz is actually doing the rendering. You might want to take a moment and study the site.

Here is the link to Mermaid: https://mermaid-js.github.io/mermaid/#/

Graphviz is even better: you can generate SVGs and PNGs that can be displayed without jabbascript

cool stuff

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact