Maven Multi-Module Projects, Parent POMs, Aggregation, Inheritance, and Reactor Builds: Concepts, Architecture, and Mental Model

1. The problem: one repository contains several independently addressable projects

A single Maven project has one POM, one project coordinate, one source tree, and one lifecycle execution context. A large repository quickly needs more than that: reusable libraries, applications, adapters, generated-code projects, test fixtures, or platform BOMs may need separate coordinates and separate dependency edges while still being built together.

The dangerous shortcut is to call every relationship “parent/child.” Maven uses at least four different relationships that can overlap but are not equivalent: aggregation says which projects a reactor collects; inheritance says which POM contributes model values; dependency edges say which artifacts a module consumes; and reactor selection says which collected projects Maven will actually build for one invocation.

2. Define the objects before touching the build

3. Aggregation and inheritance can coincide—but they remain independent

A common repository uses one root POM as both aggregator and parent. That is convenient because the root lists modules and also centralizes versions/properties/plugins. But Maven explicitly allows the roles to diverge. A corporate parent can live in a separate repository and be consumed by many services, while each service repository has its own local aggregator. Conversely, an aggregator can collect projects that inherit from different parents.

4. Reactor sorting is topological, not alphabetical or directory order

The Maven 3 multi-module guide documents the ordering relationships used by the reactor. An actual project dependency on another reactor project creates an ordering edge. So can an in-reactor plugin declaration, plugin dependency, or build extension. Only when no stronger relationship applies does the order in <modules> act as the fallback.

5. Parent resolution is model construction, not reactor dependency resolution

When Maven builds a child model, it must resolve the parent POM. The normal default relativePath is ../pom.xml. An explicit path can point elsewhere. If the local path does not identify the requested parent coordinates, Maven can fall back to repository resolution according to Maven's model-building rules and available repositories.

This is why a stale installed parent can make a broken repository layout appear healthy. A clean-room check should use a fresh project-local repository when you are testing whether parent resolution really comes from the intended source tree.

<parent>
  <groupId>dev.academy.reactor</groupId>
  <artifactId>reactor-lab-parent</artifactId>
  <version>1.0.0</version>
  <relativePath>../pom.xml</relativePath>
</parent>

6. Read-only inspection before mutation

Before adding modules or changing a parent, capture current identity and effective model evidence. In a multi-module project, run commands from the intended aggregator directory unless the lesson explicitly asks you to test another starting POM.

set -o pipefail
./mvnw -v
./mvnw -Dmaven.repo.local="$PWD/.lab-m2" help:effective-pom -Doutput=evidence-effective-root.xml
./mvnw -Dmaven.repo.local="$PWD/.lab-m2" help:effective-pom -pl :greeter-app -Doutput=evidence-effective-app.xml
./mvnw -Dmaven.repo.local="$PWD/.lab-m2" dependency:tree -pl :greeter-app

help:effective-pom reveals inherited and managed model state. dependency:tree reveals actual artifact dependencies. Neither should be confused with the aggregator's module list.

7. Reactor selectors are scope controls, not dependency declarations

8. Multi-module state stores must stay distinct

9. Parent POMs and modules expand the build trust boundary

A parent POM can inject repositories, plugin repositories, build plugins, plugin executions, properties, profiles, reporting, and dependency management into many children. An aggregator can cause many modules to execute in one invocation. Treat both as executable build-policy inputs that require code review.

10. DevOps operating contract

CI should know which root POM defines the reactor, which parent defines shared policy, which modules changed, and which dependency edges require upstream or downstream builds. A fast targeted build is useful only if its selection is graph-correct. A pipeline that silently relies on an agent's previously installed module is not proving the repository can build from source.

Knowledge check

11. Summary and next bridge

Chapter 09 starts with one discipline: draw the graphs separately. Aggregation determines collection. Parent inheritance determines model composition. Dependencies determine artifact/classpath relationships and often reactor order. CLI selection determines what one invocation builds. Lesson 2 now turns that model into a small reproducible reactor.

Official references and version notes

Version-sensitive statements in this lesson were checked against Apache Maven primary documentation on 2026-08-23. The mandatory path uses Maven 3.9.16 through Maven Wrapper 3.3.4, JDK 21 to run Maven, Java 17 as the project release target, Help Plugin 3.5.2, Dependency Plugin 3.11.0, Compiler Plugin 3.15.0, Surefire 3.5.6, and JAR Plugin 3.5.1. Maven 4 terminology is called out only where it differs materially; the hands-on path remains Maven 3.9.16.

• Maven — Guide to Working with Multiple Modules (Maven 3)
• Maven — POM Reference: Inheritance and Aggregation
• Maven — Introduction to the POM
• Maven — Maven Model Builder
• Maven — CLI Reference
• Maven Help Plugin 3.5.2
• Maven Dependency Plugin 3.11.0
• Maven Compiler Plugin 3.15.0
• Maven Surefire Plugin 3.5.6
• Maven JAR Plugin 3.5.1
• Apache Maven Wrapper
• Maven 3.9.16 Release Notes
• Maven 4 Multi-Subproject Guide — comparison only