Expose base package + some sub-packages as one module

[marinusgeuze]

Hello,

Reading the documentation it states:

an application module’s base package is considered the API package and thus is the only package to allow incoming dependencies from other modules.

However, I like to organise my packages with sub-packages instead of having all my classes in the base package. I'd like the ability to organise them.

Is there a way Spring Modulith can be configured to allow the package and all of it's subpackages to be included as a dependency without having to define named interfaces for each of the subpackages?

In my situation, there's a module relation from the 'household' module to the 'budgetdefinition' module, both of which are functional modules. Within my 'budgetdefinition' module, I've established a well-organized package structure for different types of classes, enhancing the overall code structure within the module. However, this approach requires me to define NamedInterfaces for each package and add them as allowed packages in my 'household' module.

Below, you'll find some output and code snippets for reference. Is there a more elegant solution to address this?

NOTE: This is an example project with only a few classes, but in our production code we have many more commands, events, projections, etc in one module.

Budgetdefinition
Logical name: budgetdefinition
Base package: nl.householdfinancialsystem.budgetdefinition

Named interfaces:
NamedInterface: name=<>, types=[]
NamedInterface: name=command, types=[ n.h.b.d.c.AddBudgetDefinition ]
NamedInterface: name=event, types=[ n.h.b.d.e.BudgetDefinitionAdded ]
NamedInterface: name=query, types=[ n.h.b.d.q.BudgetDefinitionProjection ]
NamedInterface: name=service, types=[ n.h.b.d.s.BudgetDefinitionCommandService, n.h.b.d.s.BudgetDefinitionQueryService ]

@org.springframework.modulith.ApplicationModule(
allowedDependencies = {
"budgetdefinition::command",
"budgetdefinition::event",
"budgetdefinition::query",
"budgetdefinition::service",
})
package nl.householdfinancialsystem.household;

[odrotbohm]

Is there a more elegant solution to address this?

There is, and – to be blunt – it is not using packages to group types by stereotype. Packages are a means of encapsulation, which is fundamentally subverted if you use them in a way that all important relationships between those elements have to be established across package boundaries. I describe that phenomenon and why it's a bad idea in my Spring Modulith talks (an extended version of this to be found here). Considering this, I think you should see the difficulty you face as messenger that you do something that subverts the original goal, in this case establishing modularity within a codebase. The second hint about that is the fact that you apparently need to make (almost) all code of a module accessible to others. Again, that's the opposite of what we're trying to achieve.

One option to get around this problem is to avoid the stereotype packages and rather use, for example, the jMolecules annotations to explicitly mark stereotype types for easier navigation.

For 1.2 we are considering introducing the concept of “open modules” that will not hide internals by default. That said, this will be introduced to allow Spring Modulith being used in legacy migrations to mark “modules” that have not been fully modularized. I.e., it's duct tape to avoid the verification from reporting violations that cannot be resolved immediately. It's not something we're going to recommend as general modeling means for new applications that intend to be modularized properly.

[marinusgeuze]

Dear Oliver,

I appreciate your comprehensive response. I thoroughly enjoyed the one-hour version of your talk, having watched it twice already :-). I plan to delve into the extended version as well before reaching out with any follow-up questions. I still have inquiries, particularly regarding the navigation of types and maintaining a clear overview, as I am not fond of packages containing a multitude of classes.

[marinusgeuze]

Dear Oliver,

Last week I watched the extended version of your talk and was impressed again by the direction and capabilities of Spring Modulith. Consequently, we are contemplating adopting it for our project.

While I understand your emphasis on using packages for encapsulation, in practical terms, we also use packages to manage cognitive load, ensuring a manageable number of classes within each package. In our project, we employ command, event, and projection records to conceal the internals (service implementations, aggregates, value objects, repositories). Allow me to illustrate with some brief code snippets:

Command
public record AddBudgetDefinition(UUID uuid, String name) {}

Event (fired as domain event by command service)
public record BudgetDefinitionAdded(UUID uuid, String name) {}

Projection
public record BudgetDefinitionFindAllProjection(String budgetDefinitionId, String name) {}

CommandService

public interface BudgetDefinitionCommandService {

    void handle(AddBudgetDefinition addBudgetDefinition);

Query Service

public interface BudgetDefinitionQueryService {

    List<BudgetDefinitionFindAllProjection> findAll();

By adopting this approach, we generate numerous commands, events, and projection records. Placing them in the top-level module package would result in a significantly large package (see picture below for example with a modest amount of commands/event/projections). While transitioning to this approach poses a substantial change for us, we are exploring whether employing jMolecules annotations to stereotype types for easier navigation could aid in this shift.

Nevertheless, I am inclined towards our current approach, advocating for exposing classes in the top-level module package alongside the command, query, and event subpackages as one module (without using named interfaces). I have attached the picture below for a clearer representation of our current structure.

I eagerly await your response and insights on this matter.

Best regards,
Marinus

[odrotbohm]

It's always a bit difficult to evaluate these arrangements with only one, “serving” module in the picture. There are a couple of aspects to the general arrangement, that I find (read: we're moving towards personal opinion here) debatable:

1. The ratio between types to be exposed and types hidden seems to imply low encapsulation. If almost all types of a module need to be made visible to other modules, it's difficult to achieve modularity. The relationship to the other modules will be established by many relations, in turn implying tight coupling. This is not a critique about your design, but a consequence of all of these separation-of-concerns architectures as they all usually employ abstractions mapped to types, which usually leads to a proliferation of commands, queries as types etc. While one can argue that there's no difference between one type exposing 5 methods being called VS. five types with one method called, I still think that the cognitive load browsing such a latter arrangement is higher. The file tree gets more cluttered, the number of editor (and thus context) switches increases. Which ultimately leads me to…
2. Should the technical decomposition be exposed to other modules at all? Wouldn't you rather either create facades that expose the API to be invoked by other modules and hide all technical decomposition behind that? Spring Modulith generally advocates event-based communication across module boundaries, exactly because that avoids the module API cluttering problem. Alternatively, consider the facade approach described above and keep all the technical composition hidden behind that.

I realize that this doesn't ultimately answer the question at hand, but it feels to me that there's benefit in thinking about how to avoid the problem rather than trying to solve it. That said, it's of course not the end of the world to continue the path you already took. I'm just afraid that Spring Modulith will not be of too much help with that.

[marinusgeuze]

Thank you once again for your comprehensive response. I think that sometimes it needs time to let something new truly settle in. Your assistance has been invaluable in this process, and I truly appreciate it.

Upon reflection, I've come to realize that only a fraction of my commands/query types might be utilized by other modules, as most are solely exposed through the REST Controllers within the module itself. To confirm this, I intend to conduct an spike within our production codebase. If I am correct, I can simplify matters by incorporating these commands/query types into the public base package while keeping the others internal.

In cases where modules exhibit tighter coupling due to legitimate reasons, the use of the facade approach could offer a good solution.

One more question. You state that you advocate the event-based communication. My assumption is that the events in that case are also part of the public module interface. Do you prefer in that case a record/class per event of do you prefer to use a Events class with the events as inner classes?