One of the reasons is the "model-code gap", as described by @GHFairbanks in his book...
Ever tried to automatically create a diagram from code? It doesn't work well, because the tooling is essentially just reflecting what it sees in the code.
Here's an example - it's an old version of the @springframework PetClinic application. If you load the code into an IDE, and ask it to create a diagram, you'll get something like this. 
Remember, this is a sample/toy app, and magnitudes smaller than anything you're probably working on yourself. The diagram is useless, because it's showing every interface, every class, every relationship.
Something you can do is remove the elements that are not particularly relevant to having an "architecture discussion". The strategy varies between codebases, but here we can remove the domain classes (data structures), and the util classes (I hope they are not important!).
Move the elements around a bit, and you can start to see the layered architecture making an appearance. And that's useful, but this is a small application. But this approach doesn't scale well for real-world codebases.
What we really want to do is "zoom out". By this I mean, move up one level of abstraction. How you do this is your choice, but I recommend the abstraction levels behind the C4 model (c4model.com): Software systems -> containers (not Docker!) -> components -> code.
So the "zoom out" here is moving from code to components. But wait, what's a component? And how do you identify components in any given codebase?
A component in the C4 model is a grouping of related functionality (e.g. public interface, private implementation), running inside a container (again, not Docker!). In simple terms, it's a grouping of code elements.
As to how you identify components, well that's up to you, and it depends how you've structured your codebase: package by layer, package by feature, package by component, ports & adapters, hexagonal, clean architecture, etc.
Given a little knowledge of the Spring PetClinic codebase, here's what I think are the components.
And therefore, the "zoomed out" version becomes something like this.
The problem, as Clemens points out, is that this set of "components" doesn't exist in the code ... at least not in any standard format that we can identify automatically.
And that's the model-code gap ... the way we think of our codebase from a top-down perspective doesn't usually match up with the code, because the architectural concepts and intent is (typically) lost in the code.
So ... how do we fix this? Step 1 is to understand how you think about your codebase. What's the overall style (layers, features, ports and adapters, etc)? And what principles went into creating the codebase (e.g. consistent naming, packaging, and accessibility conventions)?
If you're able to list out a handful of patterns/rules/heuristics that you can use to identify components in your codebase, you then have a chance to automate that process.
Rules/patterns/heuristics include:
- HTML/API controllers are built from classes named "*Controller", or have a "Controller" annotation/attribute.
- Data layer components are built from interfaces named "*Repository".
- Each component sits in a separate Java module.
- etc...
- HTML/API controllers are built from classes named "*Controller", or have a "Controller" annotation/attribute.
- Data layer components are built from interfaces named "*Repository".
- Each component sits in a separate Java module.
- etc...
There will always be exceptions, and I'm not sure that identifying 100% of your components should be the goal. But with a decent codebase, you can get to 70+% quite quickly ... if your team has been consistent. 😂
From a technical perspective, I have some open source libraries that can help; both of which have "component finders" that you can configure to find components in a codebase via reflection.
- github.com/structurizr/ja…
- github.com/structurizr/do…
- github.com/structurizr/ja…
- github.com/structurizr/do…
The Spring PetClinic component diagram (above) was created automatically using this technique -> github.com/structurizr/ja…
As a technique, it does work - I use it myself. The irony here is that it requires a well organised codebase to work. And once you have that, you often find that you don't need those component level diagrams so much ... because the code is easy to work with, maintain, navigate.
And, to pick up on my earlier thread, creating your component model using code allows you to choose multiple visualisation/output formats.
Here we have Graphviz, PlantUML, and @structurizr (x2).
Here we have Graphviz, PlantUML, and @structurizr (x2).
