r/softwarearchitecture • u/Obvious_Gap_5768 • 18h ago
Tool/Product Every architecture diagram is either useless or unreadable, so I made one you zoom into instead
Architecture diagrams have two failure modes. Three boxes that say nothing, or a hairball of two thousand nodes that says everything at once, which is also nothing. Both get screenshotted for a deck and never opened again.
Neiither answers the question you actually have in a new repo, which is not "what connects to what". It is "where am I, and does this matter".
So I built the other thing. A map you zoom into
The whole repo is one card. Zoom in and it opens into layers, then folders, then files, then functions. It is continuous, like a map app going from country to street. No level dropdown, no reload, no re-layout between steps, so you never lose your place.
The key thing: you never look at the whole repo at once. At any level you see a handful of cards, and you dig deeper only where it matters. It is something you navigate, not one dense picture you stare at. And it is not drawn by hand. It is generated from the code and git history and stays current as you commit, so it cannot hallucinate a module or drift from reality.
What makes it readable:
Cards are sized by how the system runs, not by line count. Entry points, what everything routes through, what churns. The code you should look at first is physically the biggest thing on screen.
Each card carries a health dot, rolled up so a folder reflects everything inside it. You find the bad neighbourhood from orbit and then dive.
Edges only appear when you hover a box, and only that box's edges, curved around the other cards rather than through them. That single decision is most of the difference between a map and a hairball.
The performance answer, for anyone who assumes this dies at scale: you never draw the whole repo. Anything off screen or smaller than a couple of pixels is skipped, so a frame draws a few dozen cards whether the tree has 2,000 nodes or 10,000. Cost stops scaling with repo size, which was the point.
It is part of an open source tool I maintain called Repowise, AGPL, runs fully local. Gif is it mapping its own repo.
Link: https://github.com/repowise-dev/repowise
Edit: no, it's not just C4. C4 is four static diagrams you draw and maintain by hand. This is generated from code and git history, one continuous zoom, with card size from centrality and churn, plus co-change and health that C4 has no concept of
Edit 2: Thanks for all the feedback, the Structurizr DSL point came up enough that I am adding it as an export format, emitted as a model file you include from your own workspace so your views and styles stay yours and never get overwritten on re-index
