Dependencies that violate your target module structure need to be resolved before code can be extracted from the monolith into the new module.

This is the third post in a series that will explore the challenges of migrating a monolithic code base to a modular architecture

Series links:
Post 1 – Migrating from Monolith to Modular
Post 2 – Monolith to Modular – The Extract Module Use Case
Post 3 – Monolith to Modular – Managing Violations  – (this post)
Post 4 – Monolith to Modular – Sizing and Estimating Scope


In our previous post we described the simplest “Extract Module” scenario, in which the new module has no dependencies on the remaining monolith. This post describes the scenario where the proposed new module and remaining monolith are mutually dependent.

The circular dependency has to be resolved by removing the dependencies that violate the intended module architecture, before code can be physically moved from the monolith into the new module (build systems don’t like cycles). The refactoring to resolve these violations can be complex and time consuming, taking weeks or even months to complete.

Which leads to potential issues: –

  • What if new violations are introduced whilst the existing ones are being removed?
  • How will the developers know when all the violations are resolved?
  • How would a developer from another team know that they have created a new violation?

The combined use of 1) an Action List, 2) a Structure Spec, and 3) Structure101 Workspace is one way to resolve these issues. The Action List plus Structure Spec captures the target module architecture in Structure101 Studio. Publication of the Actions and Spec communicates this architecture to the wider team via Structure101 Workspace in their IDE. Any violations to the target architecture are highlighted in the Structure Map. The Structure Map allows a developer to quickly focus on existing code that violates the target architecture. “Spotlighting” can be used to filter the Structure Map to just the relevant code. If code changes cause new violations, these will also be highlighted in the Structure Map.

In the example below, the modules utilities, logging and nalpeiron have already been extracted from core (previous post).  For this new extraction, the remaining core has been split into 4 new modules: assemblies, comms, studio and data-models. The simulation of these new modules in Studio (Structure tab) has resulted in feedback dependencies shown as dotted lines.


The four new modules are then added to the Structure Spec which (by default) shows the same feedback dependencies. In the Structure Spec we refer to them as violations. The Action List named Module Extract is shared (indicated by the hand icon). This means the actions that created the new modules (mostly moving packages and classes) can be published to a Structure101 repository and imported into the Structure101 Workspace IDE plugin (Eclipse/IntelliJ). The Structure Spec will be published at the same time.


In the Publish dialog Publish Spec and Publish action list must both be checked. The repository project is named module-extraction.


Switching to Workspace in the IDE now…

In the Workspace settings (Eclipse in this example) the Source of specs is pointed to the repository and the module-extraction project selected.


A full refresh of the Structure101 Workspace’s Structure Map loads and applies the Action List and Structure Spec. The violations are shown as dotted red lines on the resulting Structure Map inside the IDE:


A developer working to resolve the violations can drill into the map and follow the red lines to reveal the code item causing the violations:


Alt-clicking on the code item navigates to the item in the IDE source editor where the root cause can be examined and/or refactored out.

If a new dependency is introduced that violates the architecture, it is shown in the Structure Map (again, inside the IDE) as a purple line. The names of the packages and class causing the violation will also be purple.


And a developer can drill down following the purple elements to find the offending code:


And then use spotlighting to filter the Structure Map to the relevant/dependent code:



Capturing the planned changes in the module structure and making it available in the IDE in this way gives the wider team an understanding of the to-be architecture as they continue ongoing development. And it gives the developers working to resolve the violations a dynamic navigable view of the offending code. A ‘to-do’ list of refactoring presented visually with all the attendant navigation and spotlighting functionality the structure map provides.

When all the violating dependencies have been removed, the final task is to create the module and move the source code into it from the monolith. The developer making these changes can follow the Action list step by step to implement the module creation and make the class moves that were simulated in Structure101 Studio.

In the next post we will describe how the violating dependencies can be used to build a backlog of work for planning and estimation.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.