Name: Diagrams review: generating cloud architecture diagrams from Python code
Item: Diagrams
Rating: 4.5
Author: Alex Liu

Python code to architecture diagram: how it works

`from diagrams import Diagram; from diagrams.aws.compute import EC2; from diagrams.aws.database import RDS; with Diagram('Web Service'): EC2('web') >> RDS('database')`. This generates a PNG with an EC2 box connected to an RDS box by an arrow. It has 200+ node types across AWS, GCP, Azure, Kubernetes, and on-prem. Each node uses the official provider icon. The layout is automatic (Graphviz). For standard architectures, the automatic layout is good. For complex architectures, you may need manual positioning hints.

Infrastructure as documentation: the workflow

I keep `architecture.py` in the saas.pet repo. When I add Vercel cron → GitHub API → n8n pipeline → Vercel deploy, I update `architecture.py` alongside the code. The diagram is regenerated on every build and embedded in the project README. This means the architecture diagram is never out of date. The alternative (manually updating a draw.io file) always drifts from reality because it is not in the developer workflow.

Cloud provider icons: 200+ and counting

Diagrams has comprehensive icon sets: AWS (EC2, S3, Lambda, RDS, DynamoDB, etc.), GCP (Compute Engine, Cloud Storage, Cloud Functions), Azure (VMs, Blob Storage, Functions), Kubernetes (Pods, Services, Ingress), and generic (database, queue, load balancer). Each icon is the official provider icon, which matters for client-facing documentation where wrong icons look unprofessional.

When the automatic layout fails

For architectures with 30+ nodes and complex interconnections, Graphviz's automatic layout produces spaghetti. Lines cross, nodes cluster oddly, and the diagram becomes unreadable. For these cases, Diagrams supports clusters (grouping nodes into boxes), edge constraints (force horizontal or vertical alignment), and manual positioning via Graphviz attributes. Fixing a bad automatic layout takes 10-30 minutes of trial and error. For simple architectures, layout is instant.

Diagrams vs draw.io vs Excalidraw vs Terraform graph

Diagrams: code-based, auto-generated, version-controlled. Best for infrastructure docs that change frequently. draw.io: manual, most control, best for one-off diagrams that need pixel-perfect layout. Excalidraw: hand-drawn aesthetic, collaborative, best for design discussions. Terraform graph: auto-generated from Terraform state, always accurate, limited visual customization.

Frequently Asked Questions

Is Diagrams worth the subscription or should I just use ChatGPT?

Notion AI wins for users already in the Notion ecosystem. ChatGPT wins for general-purpose AI. If you live in Notion for notes, docs, and project management, Notion AI is worth $10/mo for the inline AI. If you just want an AI assistant, ChatGPT at $20/mo is more versatile. I use both: Notion AI for inline writing, ChatGPT for research and code.

How much time does Diagrams actually save per day?

I tracked my Notion AI usage for a month. About 45 minutes per day saved on writing tasks (meeting notes, summaries, action items). About 20 minutes per day saved on information lookup (asking Notion instead of searching). Total: 65 minutes per day = 8 hours per week. Worth $10/mo easily for a knowledge worker.

Can Diagrams replace a project management tool like Asana or Trello?

Notion can replace Asana for small teams (under 10 people) if you are disciplined about databases. For larger teams, Asana is more reliable. Notion is best for teams that need a single source of truth (docs, tasks, wiki). Asana is best for teams that need pure task management. I use Notion for everything except time-sensitive tasks.

Will Diagrams replace my note-taking app like Evernote or Apple Notes?

For most people, yes. Notion combines notes, tasks, databases, and wikis in one app. Evernote is just notes. Apple Notes is just notes. Notion is the only one that grows with you. I migrated from Evernote to Notion in 2024 and never looked back. The AI features are a bonus on top of the structure.

Diagrams review: generating cloud architecture diagrams from Python code