Skip to content

Latest commit

 

History

History
266 lines (186 loc) · 11.8 KB

diagrams.md

File metadata and controls

266 lines (186 loc) · 11.8 KB

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

Important Icon Sets

Especially to import into D2, but also to supplement other languages and libraries as necessary.

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

Interactive Playground Editors

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

Ported from various private Knowledge Base pages 2020+