Grounding Beliefs

How to automate architecture docs

•2 min read
Grounding Beliefs

If you came for the docs, head over to the repo.

Grounding Beliefs

I saw a tweet last year that stuck with me:

That’s exactly what I’d been doing—manually drawing module graphs, watching them go stale, then redrawing them. Even after switching to Mermaid.js for version control, I was still maintaining them by hand. The tweet forced the question: why not generate them from the source code itself?

The Evolution of Tooling

I’ve used diagrams for years. Started on whiteboards, moved to diagrams.net for remote work, then Excalidraw for cleaner output. The “as-code” tools like Mermaid and PlantUML were an improvement—I could diff them, version them, and check them in.

But they were still static artifacts I had to remember to update. The tweet made me realize that was a bug, not a feature.

Prior Art

Before building anything, I looked for existing solutions. Jake Wharton had a script that parsed Gradle projects and emitted Graphviz DOT files.

It worked, but added a binary dependency and produced JPGs—useless for diffs and clunky in CI. I wanted something lighter that output plain text and ran anywhere.

From Script to Plugin

The result is a Gradle plugin that introspects your module dependencies and writes a Mermaid graph directly into your README. No external binaries, no manual steps.

I started with a POC and eventually published the full plugin to the Gradle Portal.

To get started, apply the plugin and run:

./gradlew createModuleGraph

You get a live module diagram that’s readable on GitHub and GitLab:

It should look something like this

It should look something like this

Wrapping Up

It’s a single task that hooks into the build graph without getting in the way. The code is on GitHub. CI integration is trivial—just run the task and commit the delta.

This is my first plugin, so I expect rough edges. Issues and PRs welcome.

#automation,  #gradle,  #architecture