Skip to content

Instantly share code, notes, and snippets.

@HariSekhon

HariSekhon/diagrams.md

Last active July 20, 2025 16:39
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save HariSekhon/cb53b7622791718f1ee9d8709c9eec35 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save HariSekhon/cb53b7622791718f1ee9d8709c9eec35 to your computer and use it in GitHub Desktop.
Download ZIP
diagrams.md from HariSekhon/Knowledge-Base repo: https://github.com/HariSekhon/Knowledge-Base
Raw
diagrams.md

Diagrams

Diagrams are key for top architects and engineers.

The ability to create meaningful diagrams is the pinnacle of communication skills as an engineer

There are GUI architecture tools, but they tend to be more difficult to reproduce, you're often starting from scratch for each client.

The cutting edge is Diagrams-as-Code.

See also the Documentation and Markdown pages for tips on things like embedding diagrams in README.md, as well Badges.

Real World Architecture Diagrams

HariSekhon/Diagrams-as-Code - ready made architecture diagrams

Mainly D2lang, Python diagrams, MermaidJS, GNUplot and a little Draw.io / LucidChart.

GitHub Actions CI/CD pipelines auto-regenerate the diagrams upon any code changes and they appear directly in the rendered README.md as the resultant .png images are sourced in the markdown code.

Readme Card

Templates

Templates for D2 language and Python diagrams are found here, especially diagram.d2 and diagram.py.

Readme Card

Diagrams-as-Code Languages

Text-to-Diagram Comparison Playground

Diagrams-as-Code are both cool, easier to reuse prior work and often easier to maintain.

A quick edit and they reshuffle themselves.

The lack of placement layout control (D2 issue #1285, Python Diagrams issues #44 and #819) is the main problem on more complex diagrams, for which you may want to switch to one of the top GUI tools from the next section.

  • MermaidJS - excellent multi-format flexible diagram language with code rendering directly inside GitHub markdown (README.md) files thanks to GitHub integration
  • D2 lang - excellent, easy to use DSL for Cloud & Architecture diagrams, my favourite
    • See D2 lang doc page for details
    • See thse D2 Code files
  • Python Diagrams - my prior favourite
    • good for basic Cloud & Architecture diagrams with icons
    • See thse Python Diagrams Code files
  • GraphViz - the classic
    • its dot format is output by Terraform's terraform graph command
    • this is the technology under the hood of Python diagrams above which makes it easier to use for Pythonistas
  • GNUplot - classic code diagram CLI tool that can plot from data files in different formats and output in many different formats
    • See these GNUplot Code files
  • Go Diagrams - Golang a port of Python Diagrams
  • Cloudgram - another DSL language
  • Structurizer - C4 architecture diagrams
  • PlantUML - creates UML diagrams eg. class diagrams, sequence diagrams, use case diagrams
  • MarkMap - visualize your Markdown as mindmaps, nice, can open your GitHub repo's Markdown directly, although it looks like my DevOps-Bash-tools repo is far too huge a map

Best Comparison Site (run by D2)

GUI / Online Diagrams tools

For more control and complex architecture diagrams.

  • Draw.io - mature and can export to XML
    • integrates with Confluence to embed diagrams straight into Confluence wiki pages
  • LucidChart - used this for a GCP architecture diagram for a startup interview (I got the job)
    • pre-made VPC, region, zones - quicker to start
  • CloudCraft - cloud focused diagrams
    • still only AWS and Azure diagrams as of March 2024
  • Creately - AWS, Azure and GCP diagrams
  • Excalidraw - simple whiteboard style drawings - also useful for ad-hock drawings to explain things to colleagues
  • Miro - collaborative workflow and diagram tool
  • Prezi - focused on presentations
  • Sketch
  • Cacoo
  • Gliffy
  • Visual Paradigm - enterprise, does archimate diagrams, complicated, I used this at an investment bank, not my favourite, fine for enterprise architects rather than engineers
  • Cloudairy - new, buggy UI when I tried it
  • ASCIIflow - interactive ASCII boxes and lines, seems pretty useless
  • Swimm - AI to generate diagrams from code and documentation sources

Icons

D2lang Icons

  • D2 Icons - limited set, borrow some from Python Diagrams below

Python Diagrams Icons

Python Diagrams has the best in-built library, some highlights are below, but check their adjacent categories too:

Kubernetes & CNCF Icons

Cloud Provider Icons

Other Icon Sets

  • SeekLogo - gives icons as zip, less useful for Diagrams-as-Code
  • IconDuck - doesn't give direct download links you can use in Diagrams-as-Code

Icon Tips

If all else fails, there is always Google Image Search.

Some sites use funny tricks to stop you having direct download links.

If you Google Image search and just right-click and Open Image in New Tab, you'll get a direct asset link to a CDN or similar you can use.

However, CDN asset links tend to disappear after some months / years when websites get updated, so you should download and commit the source icon to your repo when using it in Diagrams-as-Code to prevent future time-wasting breakages.

Interactive Playground Editors

Text-to-Diagram Comparison Playground D2 MermaidJS GraphvizOnline CloudGram PlantUML Excalidraw Miro

GraphViz

in HariSekhon/Templates

generate .png using the dot command:

dot -T png template.gv -o file.png >/dev/null

open the generated .png file:

if uname -s | grep -q Darwin; then
  open file.png  # Mac
else
  sxiv file.png  # Linux
fi

or better use the imageopen.sh script from the DevOps-Bash-tools repo which tries more different tools on Linux to open the image:

HariSekhon/DevOps-Bash-tools - imageopen.sh

Hex Colour Codes

See Visualization doc's Colours section.

Diagram Design

Complexity

Diagrams-as-Code languages currently have no placement control placement layout control (D2 issue #1285, Python Diagrams issues #44 and #819).

This limits the complexity of diagrams that can be generated from code because they can very quickly get out of control and ugly as a result, costing you lots of time trying to get them to generate sane looking diagrams.

For complex diagrams you really need to switch to GUI tools for better control.

However, that being said, one diagram can only become so complicated before it becomes difficult for humans to easily interpret due to too much detail.

For this reason, I recommend favouring an approach of multiple levels of simpler diagrams:

  • an architecture overview diagram
  • sub-diagrams that drill down into the implementation details of the different components eg. how it runs on Kubernetes or with high availability

The diagrams can be more easily read one after another.

You see examples of diagrams at different levels of drill-down from architecture to Kubernetes components in the HariSekhon/Diagrams-as-Code repo.

Some components like Grafana and Vault are very relevant in architecture diagrams and should be present but can be represented by a since simple icon, with their implementation showing how they're running on Kubernetes or achieving high availability being left to separate diagrams for each one.

Diagram of Diagrams-as-Code Tools

Diagrams-as-Code tools

UML Class Diagrams

UML Class Diagrams Cheatsheet

Graph Generation Repos

Readme Card

Readme Card

Ported from various private Knowledge Base pages 2020+

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment