Architecture diagrams should be code

This page summarizes the projects mentioned and recommended in the original post on news.ycombinator.com

SurveyJS - Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App
With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
surveyjs.io
featured
InfluxDB - Power Real-Time Data Analytics at Scale
Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
www.influxdata.com
featured
  • java

    Structurizr for Java (by structurizr)

  • - https://structurizr.com/ (by Simon Brown, the creator of the C4 model)

  • diagrams

    :art: Diagram as Code for prototyping cloud system architectures

  • SurveyJS

    Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.

    SurveyJS logo
  • C4-PlantUML

    C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures

  • The C4 model (https://c4model.com/) is great for architecture diagrams. You can use different tools to generate them. Here are the ones I've been using:

    - https://github.com/plantuml-stdlib/C4-PlantUML

  • c4-notation

    Technical resources for using the C4 model for visualizing software architecture.

  • The C4 model (https://c4model.com/) is great for architecture diagrams. You can use different tools to generate them. Here are the ones I've been using:

    - https://github.com/plantuml-stdlib/C4-PlantUML

  • flowchart-fun

    Easily generate flowcharts and diagrams from text ⿻

  • I totally agree the distinction exists, just wanted to say https://flowchart.fun/ is nice because you can run layout algorithms and then tweak to your liking w/in the same editor

  • KeenWrite

    Discontinued Free, open-source, cross-platform desktop Markdown text editor with live preview, string interpolation, and math.

  • KeenWrite[0], the FOSS Markdown text editor I’ve been working on, includes the ability to render plain text diagrams via Kroki[1]†. See the screenshots[2] for examples. Here’s a sample Markdown document that was typeset[3] using ConTeXt[4] (and an early version of the Solare[5] theme).

    One reason I developed KeenWrite was to use variables inside of plain text diagrams. In the genealogy diagram, when any character name (that’s within the diagram) is updated, the diagram regenerates automatically. (The variables are defined in an external YAML file, allowing for integration with build pipelines.)

    Version 3.x containerizes the typesetting system, which greatly simplifies the installation instructions that allow typesetting Markdown into PDF files. It also opens the door to moving Kroki into the container so that diagram descriptions aren’t pushed over the Internet to be rendered.

    †Kroki, ergo KeenWrite, supports BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), Ditaa, Erd, Excalidraw, GraphViz, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, UMLet, Vega, Vega-Lite, and WaveDrom.

    Note that Mermaid diagrams generate non-conforming SVG[6], so they don’t render outside of web browsers. There is work being done to address[7] this problem.

    [0]: https://github.com/DaveJarvis/keenwrite

    [1]: https://kroki.io/

    [2]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/scree...

    [3]: https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

    [4]: https://wiki.contextgarden.net/Main_Page

    [5]: https://github.com/DaveJarvis/keenwrite-themes/

    [6]: https://github.com/mermaid-js/mermaid/issues/2485

    [7]: https://github.com/yuzutech/kroki/issues/1410

  • kroki

    Creates diagrams from textual descriptions!

  • KeenWrite[0], the FOSS Markdown text editor I’ve been working on, includes the ability to render plain text diagrams via Kroki[1]†. See the screenshots[2] for examples. Here’s a sample Markdown document that was typeset[3] using ConTeXt[4] (and an early version of the Solare[5] theme).

    One reason I developed KeenWrite was to use variables inside of plain text diagrams. In the genealogy diagram, when any character name (that’s within the diagram) is updated, the diagram regenerates automatically. (The variables are defined in an external YAML file, allowing for integration with build pipelines.)

    Version 3.x containerizes the typesetting system, which greatly simplifies the installation instructions that allow typesetting Markdown into PDF files. It also opens the door to moving Kroki into the container so that diagram descriptions aren’t pushed over the Internet to be rendered.

    Kroki, ergo KeenWrite, supports BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), Ditaa, Erd, Excalidraw, GraphViz, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, UMLet, Vega, Vega-Lite, and WaveDrom.

    Note that Mermaid diagrams generate non-conforming SVG[6], so they don’t render outside of web browsers. There is work being done to address[7] this problem.

    [0]: https://github.com/DaveJarvis/keenwrite

    [1]: https://kroki.io/

    [2]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/scree...

    [3]: https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

    [4]: https://wiki.contextgarden.net/Main_Page

    [5]: https://github.com/DaveJarvis/keenwrite-themes/

    [6]: https://github.com/mermaid-js/mermaid/issues/2485

    [7]: https://github.com/yuzutech/kroki/issues/1410

  • InfluxDB

    Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.

    InfluxDB logo
  • keenwrite-themes

    Discontinued Document typesetting configurations using ConTeXt

  • KeenWrite[0], the FOSS Markdown text editor I’ve been working on, includes the ability to render plain text diagrams via Kroki[1]†. See the screenshots[2] for examples. Here’s a sample Markdown document that was typeset[3] using ConTeXt[4] (and an early version of the Solare[5] theme).

    One reason I developed KeenWrite was to use variables inside of plain text diagrams. In the genealogy diagram, when any character name (that’s within the diagram) is updated, the diagram regenerates automatically. (The variables are defined in an external YAML file, allowing for integration with build pipelines.)

    Version 3.x containerizes the typesetting system, which greatly simplifies the installation instructions that allow typesetting Markdown into PDF files. It also opens the door to moving Kroki into the container so that diagram descriptions aren’t pushed over the Internet to be rendered.

    †Kroki, ergo KeenWrite, supports BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), Ditaa, Erd, Excalidraw, GraphViz, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, UMLet, Vega, Vega-Lite, and WaveDrom.

    Note that Mermaid diagrams generate non-conforming SVG[6], so they don’t render outside of web browsers. There is work being done to address[7] this problem.

    [0]: https://github.com/DaveJarvis/keenwrite

    [1]: https://kroki.io/

    [2]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/scree...

    [3]: https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

    [4]: https://wiki.contextgarden.net/Main_Page

    [5]: https://github.com/DaveJarvis/keenwrite-themes/

    [6]: https://github.com/mermaid-js/mermaid/issues/2485

    [7]: https://github.com/yuzutech/kroki/issues/1410

  • mermaid

    Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

  • KeenWrite[0], the FOSS Markdown text editor I’ve been working on, includes the ability to render plain text diagrams via Kroki[1]†. See the screenshots[2] for examples. Here’s a sample Markdown document that was typeset[3] using ConTeXt[4] (and an early version of the Solare[5] theme).

    One reason I developed KeenWrite was to use variables inside of plain text diagrams. In the genealogy diagram, when any character name (that’s within the diagram) is updated, the diagram regenerates automatically. (The variables are defined in an external YAML file, allowing for integration with build pipelines.)

    Version 3.x containerizes the typesetting system, which greatly simplifies the installation instructions that allow typesetting Markdown into PDF files. It also opens the door to moving Kroki into the container so that diagram descriptions aren’t pushed over the Internet to be rendered.

    †Kroki, ergo KeenWrite, supports BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), Ditaa, Erd, Excalidraw, GraphViz, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, UMLet, Vega, Vega-Lite, and WaveDrom.

    Note that Mermaid diagrams generate non-conforming SVG[6], so they don’t render outside of web browsers. There is work being done to address[7] this problem.

    [0]: https://github.com/DaveJarvis/keenwrite

    [1]: https://kroki.io/

    [2]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/scree...

    [3]: https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

    [4]: https://wiki.contextgarden.net/Main_Page

    [5]: https://github.com/DaveJarvis/keenwrite-themes/

    [6]: https://github.com/mermaid-js/mermaid/issues/2485

    [7]: https://github.com/yuzutech/kroki/issues/1410

  • asciiflow

    ASCIIFlow

  • This is perhaps a tangent, but I've used https://asciiflow.com/#/ a few times now to insert diagrams into my source code as comments. I understand people might have negative opinions on the efficacy of comments that this would only exacerbate, but nevertheless I've appreciated what AsciiFlow gave me.

  • foam3

    FOAM: Feature-Oriented Active Modeller, Version 3 (unstable)

  • Sort of related but an interesting idea is take it one step further with the Feature Oriented Active Modeler (FOAM) [1,2] paradigm and use code to model your whole system, which generates diagrams model, and runnable code in whatever language needed. The project is still young and it may not be practical today with the available tooling but it seems like a cool idea and project. It is influenced by the unix principle of “coding the perimeter not the area” which is essentially factoring your dev tasks into building NM capabilities, but instead of building NM things individually build N+M tools that can be composed into N*M capabilities [2].

    So with FOAM the idea is if we want to maintain a model of our software, and build it as well, what if we can use one composable tool to generate both, rather than model everything and code it separately.

    [1] https://github.com/kgrgreer/foam3

    [2] https://foam-framework.github.io/foam/

    [3] https://m.youtube.com/watch?v=3Ea3pkTCYx4

  • excalidraw

    Virtual whiteboard for sketching hand-drawn like diagrams

  • Yes! I use https://excalidraw.com/ for this. Its free and open source, is super easy to use, runs locally, looks nice without folks getting the impression it's a source of truth

  • TALA

    A diagram layout engine designed specifically for software architecture diagrams

  • This is a problem with the languages, not a fundamental flaw. Manipulating text has a much higher ceiling than drag and drop, in terms of speed and simplicity. Every programmer has their own ecosystem for manipulating text. I can grep, version control, diff, jump with Vim key bindings, etc.

    The layout engines are very hard. We've been making https://terrastruct.com/tala for over 2 years now. At first it seemed dubious whether it was even possible to beat Graphviz, but we've been designing it to emulate how diagrams might look on a whiteboard drawn by humans. That's a very different heuristic than the theoretical hierarchical cross-minimizations that previous algorithms strive for, and it's yielded good results for a subset of diagrams.

  • d2

    D2 is a modern diagram scripting language that turns text to diagrams.

  • you can do this in Terrastruct (https://www.youtube.com/watch?v=EhxVVkxv2Ns), which uses the open-source D2 (https://github.com/terrastruct/d2) for its code

  • Moose

    MOOSE - Platform for software and data analysis. (by moosetechnology)

  • I use TLA+. Almost every system has some sort of safety property that needs to be guaranteed (bad things must never happen). A good many have liveness properties (something must eventually happen). Diagrams are well and good for documentation but tell you nothing about the specifications of the system.

    I tried UML once but found it lacking.

    When I’m writing documentation I like to use diagrams. Mermaid has served me well. It’s integrated into GitHub these days which is convenient. I’ve also used ditaa and graphviz to good effect. With org-mode and org-babel it’s quite easy to build executable documentation: take the query from a database to build a rough ER diagram with graphviz, a shell command on a jump box to get the data-plane hosts to build into a network diagram, etc.

    Another interesting tool: https://github.com/moosetechnology/Moose I haven’t spent that much time with it but I learned enough to generate a dependency graph for a NodeJS project that was useful for planning refactoring work.

  • SaaSHub

    SaaSHub - Software Alternatives and Reviews. SaaSHub helps you find the best software and product alternatives

    SaaSHub logo
NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a more popular project.

Suggest a related project

Related posts

  • Ask HN: Guidelines for making clear architecture diagrams

    3 projects | news.ycombinator.com | 1 May 2024
  • How to draw beautiful software architecture diagrams

    17 projects | news.ycombinator.com | 27 Oct 2023
  • Which tools do you use to create diagrams?

    5 projects | /r/golang | 18 Apr 2023
  • How to create diagrams via code?

    4 projects | /r/homelab | 1 Dec 2022
  • D2 is now open source – a new, modern language that turns text to diagrams

    34 projects | news.ycombinator.com | 22 Nov 2022