diagrams.md from HariSekhon/Knowledge-Base repo: https://github.com/HariSekhon/Knowlege-Base

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.

Real World Architecture Diagrams

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

Mainly D2 and Python diagrams, with some MermaidJS and a little Draw.io / LucidChart.

Templates

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

Diagrams Languages

• D2 lang - excellent, easy to use DSL, my favourite
  • read D2 lang for details
• Python Diagrams - my prior favourite
  • good for basic Cloud Architecture diagrams with icons
  • unfortunately no placement control for more complex diagrams
• Go Diagrams - a port of Python Diagrams
• Cloudgram - another DSL language
• 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
• MermaidJS - best for embedded live diagrams in GitHub READMEs
  • Flow Chart, Git Commit Log Charts, Gantt diagrams etc.
  • not primarily icon oriented such as for Cloud Architecture diagrams (D2 and Python diagrams are better for that)
  • can do icons though, see example by D2 comparison site
  • see HariSekhon/Diagrams-as-Code repo for live embedded MermaidJS diagrams GitHub Flow with Jira integration and Git Environment Branches
• Structurizer - yet another DSL, limited to software models
• 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

• 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
• 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
• Swimm - AI to generate diagrams from code and documentation sources

Important Icon Sets to import into D2

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

• D2 Icons

• Python Diagrams On-Premise

• Python Diagrams AWS

• Python Diagrams GCP

• Python Diagrams Azure

• Python Diagrams Generic - OS, Virtualization, Network Hardware

• Python Diagrams Kubernetes

• Official Kubernetes Icons

• CNCF technologies Icons

• SimpleIcons

• FlatIcon

• IconFinder

• Icons8

• Official AWS Icons

• Official GCP Icons

• Official Azure Icons

• Benco Azure Icons

• Icon8 Azure Icons

Interactive Playground Editors

• D2 lang
• MermaidJS
• CloudGram
• GraphViz:
  • https://dreampuf.github.io/GraphvizOnline
  • http://magjac.com/graphviz-visual-editor/
  • https://edotor.net/ -MarkMap
• Draw.io:
  • Draw.io pre-loaded with AWS, GCP and Azure icons
  • Draw.io pre-loaded with AWS icons
  • Draw.io pre-loaded with Azure icons
  • Draw.io pre-loaded with GCP icons
• LucidChart
• CloudCraft
• Creately
• Visual Paradigm
  • Online Dashboard
• Structurizer

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

Ported from various private Knowledge Base pages 2020+