Codify the Rules You Use to Organize Your Code

regular readers will already know about structurizr — a set of open source libraries to create a software architecture model as code, plus a saas product to visualize those models. having created and helped create a number of models with structurizr now, i've noticed an interesting side-effect. in the absence of architectural information being present in the code, the power of using something like structurizr to define a software architecture model using code is in extracting information algorithmically, by codifying the rules that you've ultimately used to structure your codebase.

let me give you an example. imagine you're building a web-mvc web application in java, c#, etc. and you have a tens or hundreds of controller classes, each of which uses a number of other components to implement some functionality. drawing a single diagram to visualize the static structure of the entire web application is a bad idea because it shows too much information. a better approach is to create one view per vertical slice , where there could be one vertical slice per web controller. this results in smaller, simpler diagrams like this.

so far, so good, and this is relatively easy to do using static analysis techniques. but you'll notice this diagram includes an "authenticated user", which isn't part of the code itself. this raises the question of how the user ends up getting included on the diagram.

there are a number of options:

• manually add the correct type of user on a case by case basis.
• match the controller's url routing to the permitted user role (this is likely specified in configuration somewhere) and use this information to choose the appropriate type of user for each controller.
• add machine-readable metadata (e.g. java annotations, c# attributes) to specify the user type (there are some structurizr annotations i've created to help with this).
• codify the rules you've used to organize the controllers in your codebase.

the ability to codify the rules you've used to organize the controllers in your codebase obviously depends on how much thought you've put into doing this. for example, did you dump all of these controller classes into a single package or namespace without giving it much thought at all? or perhaps you took martin fowler's advice and modularised further , creating one package/namespace per functional area or aggregate root, for example. another possibility is that you grouped controllers together based upon whether unauthenticated users, authenticated users or other software systems are using them. organising your code well provides you with another angle to extract architectural information, because you can codify rules such as, "the anonymous user uses all controllers in the com.mycompany.mywebapp.unsecured package/namespace".

with hindsight this is fairly obvious, but we often don't put enough thought into how we organize our code, possibly because we perceive that it doesn't actually matter that much and modern ides provide powerful ways to navigate large and/or complex codebases. trying to codify the rules used to organize a codebase certainly gets you thinking, and often refactoring too.