Auto-Generating Architecture Diagrams from Code

Why Auto-Generate Diagrams?

Manual architecture diagrams have a fundamental problem: they go stale. The moment someone adds a new service, changes a dependency, or migrates a database table, the diagram is out of date. And outdated diagrams are worse than no diagrams — they actively mislead.

Auto-generation solves this by treating diagrams as build artifacts. Just as you compile code to produce binaries, you compile your codebase to produce diagrams. Run the tool in CI, and every merge produces an up-to-date visual.

1. Dependency Graphs from Source Code

The most common auto-generation use case is visualizing module dependencies within a codebase. These tools analyze import/require statements and produce a graph showing how modules connect:

• Madge — Generates dependency graphs for JavaScript/TypeScript projects. Outputs DOT format (Graphviz) or SVG directly. madge --image graph.svg src/ produces a complete dependency visualization.
• dependency-cruiser — More powerful than Madge, with rule-based validation. Can flag circular dependencies, orphan modules, and forbidden import paths while generating the visual graph.
• Webpack Bundle Analyzer — Visualizes the output bundle rather than source dependencies. Useful for understanding what ships to users, not how code is organized.

2. Infrastructure Diagrams

If your infrastructure is defined as code (Terraform, Pulumi, CloudFormation), you can generate architecture diagrams directly from it:

• Terraform Graph — Built into Terraform. terraform graph | dot -Tsvg > infra.svgproduces a resource dependency graph. The output is accurate but visually raw — you'll want to convert it to a more editable format.
• Inframap — Reads Terraform state files and generates cleaner diagrams than terraform graph. Groups resources by type and filters out internal Terraform dependencies.
• Diagrams (Python library)— Not strictly auto-generation, but lets you define infrastructure diagrams in Python code. Since it's code, it can import variables from your actual infrastructure config to stay in sync.

3. API and Service Maps

For microservice architectures, understanding which services talk to each other is critical. Several tools generate these maps:

• Backstage (Spotify) — The service catalog includes auto-generated dependency graphs based on service metadata. If your team uses Backstage, the diagram is always current.
• Structurizr — Implements the C4 model. You define your architecture in code (Java, .NET, or DSL), and Structurizr generates context, container, component, and code-level diagrams.
• OpenAPI/Swagger— Not a diagram tool per se, but the API specification can be used to generate interaction diagrams between services that call each other's endpoints.

4. Database Schema Diagrams

ER diagrams are among the easiest to auto-generate because the schema is the source of truth:

• SchemaSpy — Connects to a running database and generates a full ER diagram with relationship lines, column types, and foreign key annotations.
• DBML CLI — If you define schemas in DBML (Database Markup Language), the CLI generates SVG or PNG diagrams. DBML files live in your repo and can be reviewed in PRs.
• Prisma ERD Generator — For teams using Prisma ORM, this plugin generates ER diagrams directly from your schema.prisma file on every build.

Integrating with CI/CD

The real power of auto-generation is running it in CI so diagrams update on every merge:

# .github/workflows/diagrams.yml
name: Update Architecture Diagrams
on:
  push:
    branches: [main]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx madge --image docs/dependency-graph.svg src/
      - run: npx dbml-cli render schema.dbml -o docs/er-diagram.svg
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update auto-generated diagrams"

This ensures your documentation always reflects the current state of the code. The SVG outputs can then be converted to other formats (Draw.io, Excalidraw) if teams need to edit or annotate them.

Limitations and When to Hand-Draw

Auto-generated diagrams are excellent for accuracy but poor at narrative. They show what exists, not why it's designed that way. For these purposes, hand-crafted diagrams remain essential:

• High-level system overviews that tell a story
• Sequence diagrams showing specific user flows
• Decision architecture records (ADRs) with visual context
• Onboarding diagrams that highlight what new engineers need to know first

The ideal setup is a combination: auto-generated diagrams for factual accuracy (what services exist, how they connect) and hand-crafted diagrams for architectural narrative (why the system is designed this way).