Validating internal structure / dependencies using IntelliJ IDEA

There are several different tools to maintain the internal structure of a java application available. The tools range from simple open source software like jdepend and degraph to full fledged architecture tooling like Structure101 or Sonargraph Architect. All these provide methods to define the internal structure of an application and validate it somehow.
Since we are using IntelliJ IDEA in many of our teams I’d like to show a handy little feature of the IDE that helps in maintaining a structured application: In IDEA you can define scopes and match your code to them. You can then rule how they may or may not access each other using the Dependency Viewer. As soon as you do this the IDE warns you about illegal package access just as you type. Note that the shown features currently work in the free IntelliJ IDEA Community Edition.
Imagine we have a simple layered application with Java packages representing these layers:

  • api: API-Layer features controllers that are responsible to render a RESTful API to our application
  • business: our higher level operations/business logic happens here
  • persistence: this layer is responsible for storing data and providing access to it
  • domain: In addition we have a domain “layer” where all the layers share their common domain

We can now define scopes for each of these layers. We can do so using File -> Settings and then select Appearance & Behaviour -> Scopes. Here we can add new scopes and assign files to it using a pattern or by navigating to the corresponding packages and include/exclude them.
Creating Scopes using Settings
We then define archuitectural constraints on these scopes using the Analyze Dependencies View (accessible using the Analyze Menu). We do so by clicking the Edit Rules Icon in the Dependency-View.
Defining rules
In the example above configured simple constraints for our layered architecture: We only allow access between layers from an upper layer to a lower layer (API to Business and Business to Persistence) and we dont allow Domain to access any other layer.
When we return to the Dependency-View and re-run the analysis it displays all the violations of our architecture. Also, we get the analysis as soon as we type a new Validation in the Editor.
Violations view from dependencies
You can see in the screenshot that we have an illegal access from a class in scope Persistence that accesses something in scope Business. We can simply fix this by moving the Initializer to the business-Package and the error disappears.
As an alternative we can also access the information by running the analysis Illegal package dependencies (e.g. using the Analyze – > Run inspection by name) dialog. From there we can also edit our rules and navigate to the violating code.
Violations-View from inspections
If you enable the shared option for scopes IDEA will also write the configuration to .idea/scopes from where you can share them with your team members.
Scope definitions in .idea/scopes
To test and experiment with scopes yourself you can build on my my demo-project.
You can clone it from and open it using your IntelliJ IDEA (File ->Open).