Architecture diagrams should be code

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

Our great sponsors
  • Appwrite - The Open Source Firebase alternative introduces iOS support
  • InfluxDB - Access the most powerful time series database as a service
  • Sonar - Write Clean JavaScript Code. Always.
  • 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

  • Appwrite

    Appwrite - The Open Source Firebase alternative introduces iOS support . Appwrite is an open source backend server that helps you build native iOS applications much faster with realtime APIs for authentication, databases, files storage, cloud functions and much more!

  • 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

    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

    Access the most powerful time series database as a service. Ingest, store, & analyze all types of time series data in a fully-managed, purpose-built database. Keep data forever with low-cost storage and superior data compression.

  • keenwrite-themes

    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.

  • Sonar

    Write Clean JavaScript Code. Always.. Sonar helps you commit clean code every time. With over 300 unique rules to find JavaScript bugs, code smells & vulnerabilities, Sonar finds the issues while you focus on the work.

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