Skip to content

Preferred Diagram Tooling

At each stage in the engagement process, diagrams are a key part of the design review. The preferred tooling for creating and maintaining diagrams is the .drawio format from (formerly

The .drawio format uses the metadata layer within the PNG file-format to hide SVG vector graphics representation, then renders the .png when saving. This clever use of both the meta layer and image layer allows anyone to further edit the PNG file. It also renders like a normal PNG in browsers and other viewers, making it easy to transfer and embed. Furthermore, it can be edited within VSCode very easily using the Integration VSCode Extension.

This tooling can be used like Visio or LucidChart, without the licensing/remote storage concerns. Furthermore, has a collection of Azure/Office/Microsoft icons, as well as other well-known tech, so it is not only useful for swimlanes and flow diagrams, but also for architecture diagrams.

Furthermore, we recommend storing the exported PNG images from these diagrams in the repo along with the .drawio files so they can easily be referenced in documentation and more easily reviewed during PRs. Lastly, while is generally preferred, if any other diagraming tooling is used that can generate diagram images from code, both the diagram file and the image file should be stored together in the repo for the above reasons.

Last update: August 15, 2022