Build AWS architecture diagrams in VSCode

tech news
1

This shows how to build AWS architecture diagrams in VSCode Markdown with Mermaid’s architecture syntax, custom icon packs, and Markdown Preview.

Yoshiii

2

The annoying part is that it can look fine in VSCode and then render as basically nothing on GitHub.

GitHub’s Mermaid support still lags, so the newer architecture syntax and custom icon loading are where things tend to quietly break. What’s worked for me is keeping the Mermaid block in the Markdown, then exporting an SVG or PNG in CI and checking that in next to it. That way, the editable source stays in the doc, and the thing people actually see doesn’t depend on whatever GitHub feels like supporting that week.

+------------------+
|  Client / UI     |
+------------------+
         |
         v
+------------------+
|  API / Gateway   |
+------------------+
         |
         v
+------------------+
| Core Services    |
+------------------+
     |        |
     v        v
+---------+ +----------------+
|  Cache  | | Database/Store |
+---------+ +----------------+
3

GitHub’s Mermaid renderer is usually the thing that falls over, especially once you start using AWS icon packs or newer architecture elements. I’ve landed on the same workaround: keep a simple flowchart in the README, then let CI generate an architecture.svg that people actually use.

4

The CI-generated architecture. svg idea is solid, but I’d make the pipeline fail if the exported SVG changes and isn’t committed—otherwise diagrams quietly drift from the Mermaid source and nobody notices until a review fire drill.