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.
HariSekhon/Diagrams-as-Code - ready made architecture diagrams
Mainly D2 and Python diagrams, with some MermaidJS 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.
Templates for D2 language and Python diagrams are found here, especially diagram.d2 and diagram.py.
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.
- 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
- Go Diagrams - a port of Python Diagrams
- Cloudgram - another DSL language
- GraphViz - the classic
- its
dotformat is output by Terraform'sterraform graphcommand - this is the technology under the hood of Python diagrams above which makes it easier to use for Pythonistas
- its
- 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)
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
- 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
- Swimm - AI to generate diagrams from code and documentation sources
Python Diagrams has the best library, some highlights are below but check their adjacent categories too:
-
Python Diagrams Generic - OS, Virtualization, Network Hardware
- D2 lang
- MermaidJS
- CloudGram
- GraphViz:
- Draw.io:
- LucidChart
- CloudCraft
- Creately
- Visual Paradigm
- Structurizer
generate .png using the dot command:
dot -T png template.gv -o file.png >/dev/nullopen the generated .png file:
if uname -s | grep -q Darwin; then
open file.png # Mac
else
sxiv file.png # Linux
fi