Diagram Version Control: Managing Architecture Diagrams in Git

1. The Problem with Binary Diagrams

Most teams still share diagrams as PNG or PDF files. This creates several problems:

• No meaningful diffs— When someone updates a diagram, reviewers see “binary file changed” with no way to understand what changed without opening both versions side by side.
• No merge capability — Two people editing the same diagram creates a conflict that can only be resolved by redrawing one version.
• Stale documentation — Because updating diagrams is painful, they quickly fall out of sync with the actual architecture.
• Lost history — You can see that a diagram changed, but not why or how it evolved over time.

2. Choosing a Git-Friendly Format

The key to versioning diagrams is using text-based formats that produce readable diffs. Here's how the major formats compare:

• Mermaid (.mmd) — The most Git-friendly option. Plain text syntax means diffs show exactly which nodes or relationships changed. Perfect for flowcharts, sequence diagrams, and ERDs that live alongside code.
• Excalidraw (.excalidraw) — JSON-based, so diffs are readable if not beautiful. Each element is a JSON object, so adding a shape or arrow shows up as a clear addition in the diff. Good balance of visual editing and version control.
• Draw.io (.drawio) — XML-based, which is technically diffable but verbose. Style changes can produce large diffs that obscure meaningful content changes. Still far better than PNG.

3. Repository Structure

Where you put diagrams matters. Two common approaches:

• Co-located with code — Store diagrams in a docs/diagrams/ folder within the same repository as the code they document. This ensures diagrams are updated in the same PR as the code change.
• Dedicated docs repo — For cross-team architecture diagrams that span multiple services. Use a separate repository with its own review process.

Whichever approach you choose, establish a naming convention early:feature-name.type.excalidraw or service-architecture.drawio. This makes it easy to find and update the right diagram.

4. PR Review Workflow for Diagrams

The biggest cultural shift is treating diagram changes like code changes — they should be reviewed in pull requests. Here's how to make that work:

• Render previews in CI — Use GitHub Actions to render Mermaid files to SVG and post them as PR comments. Reviewers see the visual result without leaving the PR.
• Require diagram updates with code changes — If a PR changes the API layer, the architecture diagram should be updated in the same PR. Add this to your PR template checklist.
• Keep rendered versions for consumers — While the source file (.mmd, .excalidraw) is versioned in Git, also commit a rendered SVG for easy viewing in README files and wikis.

5. Multi-Format Distribution

A common challenge: your engineering team uses Excalidraw in Obsidian, but the project manager needs diagrams in Confluence (Draw.io), and the presentation deck needs SVG. Maintaining three copies manually guarantees they'll diverge.

The solution is a single source of truth with automated conversion. Store the canonical diagram in one format (e.g., .excalidraw), and use a format converter to generate the other formats on demand. Some teams even automate this in CI — a commit to the .excalidraw file triggers automatic conversion to .drawio and .svg.

6. Handling Large Diagrams

Complex architecture diagrams can produce large JSON or XML files. A few strategies to keep your repository clean:

• Split by domain — Instead of one monolithic architecture diagram, create separate diagrams for each bounded context or service area.
• Use .gitattributes — Configure Git to treat diagram files appropriately. For .excalidraw files: *.excalidraw linguist-language=JSON enables syntax highlighting in GitHub diffs.
• Compress when embedding — For Obsidian users, the excalidraw.md format uses LZ compression to keep embedded diagrams compact within markdown files.

Putting It All Together

The ideal diagram-as-code workflow in 2026 looks like this: diagrams live in Git, changes are reviewed in PRs with rendered previews, and a single source file is automatically converted to whatever formats your team needs. The tooling finally supports this — text-based formats are mature, CI integration is straightforward, and format conversion eliminates the need to maintain multiple copies.

Start with one diagram. Pick a text-based format, commit it alongside your code, and add a rendering step to your CI pipeline. Once the workflow is established, it becomes natural to keep diagrams up to date — because updating them is as easy as editing code.