Architecture Decision Records with Editable Embedded Diagrams and Version Control
Authored by Daniel Bunte, Last updated: 2025-09-07
Software must be documented with text, but more importantly, with diagrams. You’ve probably heard the phrase “a picture is worth a thousand words”—the same principle applies when comparing architecture diagrams to written documentation. To get a comprehensive overview of a software system, it’s much easier to examine a few connected boxes and immediately understand their relationships than to read 500 words describing the same situation.
Our brains excel at pattern recognition. This is why we see bunny-shaped clouds or faces in shadows where none exist. This pattern recognition ability helps us understand the world around us, and it’s equally valuable for developers and architects trying to comprehend how various components of a larger system work together.
The Documentation Crisis in Software Development
Throughout my career as a developer, head of software development, and consultant, I’ve witnessed the same pattern repeatedly: most software projects lack even basic documentation. We’re specifically talking about documentation written by developers for developers, not end-user documentation. Writing documentation feels cumbersome and becomes outdated quickly when architecture decisions change. Developers prefer writing code over documentation.
Even some managers decide not to allocate time for developer documentation—often the same people who claim “we don’t have time for refactoring or automated tests.” In my opinion, they’re missing the critical point.
Consider these scenarios where documentation becomes essential:
- New team member onboarding: Every time someone joins the team, they need to understand the system architecture
- Feature development: Each new feature should be documented for future reference
- Project handovers: When projects transfer to different agencies, comprehensive documentation becomes invaluable
The Problem with Traditional Documentation Storage
The fundamental issue is that documentation often exists in a completely separate ecosystem from the code it describes. It gets stored in wikis like Confluence or Notion, where the only way to locate these architectural descriptions is through search functionality—usually because someone accidentally moved the documentation to an entirely different location.
Even when documentation exists within these external systems, it’s frequently neglected and abandoned. This creates a vicious cycle where developers stop maintaining documentation because it’s difficult to access and update, leading to even more outdated and unreliable information.
Effective Architecture Decision Records should be stored with your codebase, ideally in your application’s version control system. This proximity ensures that ADRs are versioned alongside the code they describe, making them easily accessible to developers and keeping them synchronized with system evolution.
The Solution: ADRs with Embedded Editable Diagrams
You’re not alone in facing this documentation dilemma! Others have thought about this problem and developed better solutions. I need to credit two groups of people: first, the folks at AWS, who created an excellent Architecture Decision Record template (their ADR process is also highly recommended reading), and second, my friend Marcus Held at BackEndhance, who shared this clever trick about embeddable diagrams.
Once we acknowledge that documentation makes sense and that it should live close to the code it documents, we can conclude that all documentation should reside in the code repository. But how can we keep diagrams editable while storing them in the codebase?
The Hidden Feature: Editable Vector Images in Diagrams.net
The solution lies in an almost hidden feature within the diagrams.net application. You might need to abandon other diagramming solutions you currently use, unless they offer the same capability.
Here’s the step-by-step process:
Step 1: Create Your Diagram
Open diagrams.net and create your architecture diagram as usual.
Step 2: Save as Editable Vector Image
From the menu, select File → Save as…
Step 3: Choose the Right Format
In the file save dialog, you’ll see various format options. The exact appearance depends on your operating system, but the key is selecting “Editable Vector Image” and ensuring your file ends with .svg.
Step 4: Strategic File Placement
Save this file directly into your repository’s docs folder. Any Markdown file can now include this SVG natively and render it without issues.
Step 5: Future Editing Workflow
When your diagram needs changes, open diagrams.net and select File → Open from → Device…, then select the file directly from your repository’s docs folder.
Example diagram
The diagram shown below is an actual example of an editable SVG. You can try it by saving this file and importing it directly into the diagrams.net application.
The Multiple Benefits of This Approach
This method delivers several advantages simultaneously:
- Proper documentation location: Documentation lives where it belongs—alongside your code
- Dual functionality: Diagrams remain both editable and embeddable as images
- Version history: You get complete version control for your architectural changes
- Standard tooling: SVGs work natively in Markdown, MDX, and web browsers
- Text-based storage: Since SVGs are text-based drawing instructions, you can examine the source code in any editor
Best Practices for ADR Implementation
Effective ADRs should follow specific best practices:
1. Maintain Singular Focus
Avoid combining multiple architecture decisions in one document. Each ADR should address one core technical direction or its immediate dependencies.
2. Define Core Challenges with Context
Every ADR should begin by pinpointing a specific challenge or requirement, documenting the final choice along with its context, including team discussions, alternative solutions considered, and post-implementation results.
3. Include Status Indicators
Implement clear status indicators for each decision: “Proposed,” “Accepted,” “Deprecated,” and “Superseded”. This helps team members understand which architectural decisions are active, under consideration, or replaced by newer decisions.
4. Add Timestamps and Version Information
Each ADR should include timestamps and version information about the affected system or component. This temporal context is essential for understanding decisions as the system evolves.
Advanced Integration with Modern Development Workflows
MDX and Modern Static Site Generators
For platforms using Markdown files, or Astro with MDX, this approach works seamlessly:
---
title: "System Architecture Decision"
layout: "../layouts/ADRLayout.astro"
---
# ADR-001: Database Selection for Monitoring Data
## Context
We need to choose a database for storing website monitoring metrics...
## Decision
We chose PostgreSQL for the following reasons...
Git Integration Benefits
When ADRs and diagrams live in version control, you gain:
- Blame and history tracking: See who made specific decisions and when
- Branch-based development: Propose architectural changes through pull requests
- Automated testing: Validate documentation consistency in CI/CD pipelines
- Collaborative review: Use standard code review processes for architectural decisions
Conclusion: Building Sustainable Documentation Practices
The combination of Architecture Decision Records with editable embedded diagrams creates a sustainable documentation workflow that addresses the core problems plaguing software projects. By storing documentation alongside code and maintaining diagrams as editable SVGs, teams can:
- Reduce documentation debt through easier maintenance and updates
- Improve onboarding efficiency with visual system overviews
- Enable better architectural discussions through collaborative diagram editing
- Maintain historical context through version-controlled decision records
This approach transforms documentation from a burdensome afterthought into an integral part of the development workflow. When documentation lives where developers work and remains as easy to update as the code itself, it becomes a valuable asset rather than a maintenance burden.
For platforms focused on website monitoring and security like SiteWatch.pro, this documentation strategy becomes even more critical. Architecture decisions around monitoring systems, security implementations, and observability patterns need clear documentation that evolves with the system and remains accessible to both current team members and future contributors.
The key to success lies in making documentation creation and maintenance as frictionless as possible. By leveraging familiar tools like Git for version control and diagrams.net for visual documentation, teams can build documentation practices that actually scale with their projects and provide lasting value.
Want to learn more about building scalable monitoring and security solutions? Follow our development blog for insights into architecture decisions, technical implementations, and lessons learned from building SiteWatch.pro.
Daniel is the founder of SiteWatch.pro and has over 20 years of experience in web development and cybersecurity. He is passionate about making the web a safer place for everyone. Having knowledge in most major programming languages (Rust, Kotlin, Java, PHP, and more), he is a full-stack developer with a focus on security and performance. Daniel has deep experience from different industries, like e-commerce, gaming, energy, and more. He also holds a CompTIA PenTest+ certification, which showcases his expertise in penetration testing and security assessments.
Connect on LinkedIn.