Maintain Accurate and Up-to-Date Diagrams with Diagrams as Code

Tools for Maintaining Diagrams as Code

Play this article

Have you ever encountered outdated architecture diagrams or sequence diagrams while working on a new project and going through the documentation? This can be a frustrating and time-consuming experience, especially when you're trying to understand how the system works.

In my career so far, I've come across this situation numerous times. I've noticed that when diagrams are outdated, developers often need to spend a lot of time figuring out the updated architecture or flow, which can be a roadblock to making progress on the project. So, what's the solution?

One option is for the reader to update the diagrams themselves, which involves figuring out the updated architecture or flow using UML tools. However, this is far from ideal, and the diagrams are bound to become outdated again in the future. Additionally, not everyone may have the necessary skills or time to update the diagrams.

The better solution is to maintain the diagrams as code, which should be stored in the same repository as the code. Nowadays, there are many tools available that can help you author diagrams from code. Personally, I prefer Mermaid and PlantUML.

By keeping the diagrams in the same repository with the code, they can evolve alongside the codebase. In the long run, this can save time and effort by ensuring that the diagrams are always up-to-date and accurate. If you want the diagrams to be generated as part of your CI/CD, you may need to do some additional setup. I find it convenient to store the diagrams in a /docs folder within the project repository. This also helps to keep the documentation organized and easily accessible for everyone on the team.

An example of how the code would look in mermaid and its output are below:


flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]


  • Using UML tools like Mermaid and PlantUML to maintain diagrams as code

  • Creating a /docs folder within the project repo to maintain diagrams as code

  • Setting up CI/CD to generate diagrams as part of the build process

  • Using version control to track changes to diagrams as code

  • Integrating diagram code with project documentation

  • Automating the process of generating diagrams from code

  • Creating templates for commonly used diagram types

  • Using diagrams as code to facilitate communication between team members

  • Using diagrams as code to visualize complex architecture or data flows

  • Using diagrams as code to aid in debugging or troubleshooting code