Explaining Architecture without Code

This is going to be a bit angry rantish and not have much code.

In presentations by both Reginald Braithwaite and Robert Martin they have talked about how the code structure should map to your architecture, meaning your particular business logic. Martin talks about how looking at a base directory structure with controllers, views, and models, it tells him very little about what makes that application special.

With these thoughts in my mind I dig through code. I find a class named DiscoverySearchBuilder. I think back to the talk on the architecture I had been given by the previous maintainer. He talked about a "Discovery Phase". Is DiscoverySearchBuilder the Discovery Phase? I came to the slamming realization that the high level architecture and the code structure did not line up easily for me.

Is this a real problem and how do you solve it? I think it is a real problem. I have moved around between jobs and frequently been given the task of understanding large codebases. I often see architectural documents that are divorced from the code. Why? The answer isn't too complex. We abstract out the architecture to focus on how to present the code in a simple, clear way and not be distracted by the code. But the code and the architecture are inetricably linked. Without one, the other is meaningless. I was thinking that if you can explain your architecture by looking at your code organization you have very good code organization and if you can't you have poor organization. You should strive to have the high level explanation of your code architecture be identical to the high level explanation of your code structure.