SA-301g · Module 3

Diagram Automation

4 min read

Hand-drawn diagrams are stale from the moment they are committed. Diagram automation — generating diagrams from infrastructure code, API specifications, or runtime telemetry — produces diagrams that stay current because they are derived from the source of truth. The investment in automation pays off not in the first diagram but in the fiftieth update that happens automatically.

Do This

  • Generate deployment diagrams from infrastructure-as-code — Terraform, CloudFormation, or Pulumi configurations are the source of truth
  • Generate API diagrams from OpenAPI specifications — the specification is maintained, the diagram follows
  • Generate dependency graphs from runtime service discovery — the mesh or service registry knows what calls what

Avoid This

  • Maintain hand-drawn deployment diagrams alongside infrastructure code — they will diverge within a sprint
  • Generate diagrams without review — automation produces accurate diagrams, not necessarily readable ones; curate the layout
  • Automate every diagram — C4 Level 1 context diagrams benefit from hand-curation because they communicate strategic positioning, not implementation detail