A Good Diagram Is Worth More Than 1024 Words

But only if it is up to date. A hands-on review on Eraserbot.

Mar 27, 2025

The Problem: Stale Diagrams Create Chaos

We've all seen this meme.

It's funny because it's true. Too often, the only “reliable” source of architecture knowledge is locked inside the heads of Senior engineers, making onboarding and collaboration a nightmare.

But relying on tribal knowledge isn't sustainable. As systems evolve, outdated diagrams create more problems than they solve.

Diagrams are meant to clarify system design, helping teams understand architecture, dependencies, and workflows.

However, an outdated diagram is worse than no diagram at all. It misleads engineers, causes incorrect assumptions, and increases technical debt.

Common problems caused by stale diagrams:

Mismatched reality: The diagram shows an old architecture that no longer exists.
Wrongful assumptions: Developers make decisions based on incorrect visualizations.
Technical debt accumulation: The cost of fixing issues caused by outdated diagrams is often high.

Diagrams can go stale because:

They are created once and forgotten.
No one is responsible for updating them.
Updating them manually is time-consuming and error-prone.
Changes happen faster than documentation can keep up.

Searching for a Better Solution

I kept looking for a better way to keep diagrams accurate.

One of my favorite tools launched a feature with the promise of solving this problem—Eraserbot. Naturally, I had to test it.

For a while, we’ve seen a push toward generating diagrams from code. This helps with versioning and automation but still requires maintenance.

Now, Eraserbot is bridging this gap, ensuring diagrams stay up to date with minimal effort.

Testing Eraserbot: Real-World Scenarios

First try

I picked the Prisma repository and ran some tests using Eraserbot. Given Prisma's complex architecture and active development, it was a great candidate for evaluating how well Eraserbot handles real-world repositories.

Setting it up was straightforward; I followed this.

Then, my First prompt— Visualize the system architecture for accepting and executing a query. The diagram should cover the user-defined schemas, any servers / services, the database itself. Include query planning and security.

This was the result 🤯

Can you imagine how long this will take you?

Second try

It was an eye-opening experience. So I decided to try another repository, but this time something with more complex abstractions—Netflix Conductor.

Conductor is a workflow orchestration engine with multiple interacting services, making it a great test case for Eraserbot.

I wanted to see if Eraserbot could handle a highly distributed system, and it didn't disappoint.

First prompt — Create a sequence diagram for the workflow execution process in the Conductor repository. Examine the controllers in /server/src/main/java/com/netflix/conductor/server/resources, services in /server/src/main/java/com/netflix/conductor/service, and any relevant middleware. Illustrate the flow from workflow initiation to completion.

And… I was not disappointed.

One final test

So, I decided to test Eraserbot on something entirely different—Terraform Examples. Unlike the previous repositories, which focused on application architecture, this one is all about infrastructure as code (IaC).

Terraform configurations can be tricky to visualize, especially as they grow in complexity. I was curious to see if Eraserbot could map out the dependencies and resources.

And here we go again.

OK, that's cool, but do I need to run these prompts every time?

That was my next question. Manual prompts are great, but can this scale automatically?

Eraserbot also helps automate

One of the biggest advantages of Eraserbot is its CI/CD integrations, AKA Monitors.

It works as a continuous integration (CI) tool that automatically updates diagrams whenever changes are made to the codebase. I wasn't sure what to expect at first, but the idea of automatically updating diagrams in response to code changes was intriguing.

After setting it up on a test repository, I made a few architectural changes and watched the diagrams update in real-time with 0 effort.

How It Works:

Monitors your repository: Eraserbot watches specific files or directories in your repo.
Re-generates diagrams dynamically: When a PR introduces changes, it updates the related diagrams.
Version controls your diagrams: It keeps a record of changes, making it easy to track modifications over time.
Enhances PR reviews: It provides before-and-after visualizations, helping reviewers understand the impact of changes more effectively.

Key Takeaways

An outdated diagram is a liability. It causes confusion and leads to bad architectural decisions.
Diagrams should be treated like code. They need version control, continuous updates, and review processes.
Eraserbot simplifies the process by automating diagram updates and keeping documentation synchronized with system changes.
The best teams don't just document architecture—they keep it accurate.

Of course, it's not perfect—there's a learning curve in setting up the right configurations, and it doesn't yet cover every architecture visualization (I'm pretty sure they are working on more).

But the time saved on maintenance alone makes it worth considering for any team dealing with evolving system designs.

The future of technical documentation is automated, versioned, and always up to date—but more importantly, available at the reach of a prompt.

Thanks to the team at Eraser for collaborating with me on this post. Give it a try, and let me know your thoughts:

Try Eraserbot

System Design Classroom is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Articles I enjoyed this week

Thank you for reading System Design Classroom. If you like this post, share it with your friends!

System Design Classroom