Building a multi-module Maven project for Spring Boot

Creating a multi-module Maven project for a Spring Boot application separates business rules, reusable libraries, and executable services into focused components. Maven’s reactor builds them together while keeping each module’s dependency surface small.

The parent project owns versions and module order. Child modules can publish independently, share domain models, and expose narrow APIs without copying configuration. This reduces duplicated code and limits the impact of changes.

Australian teams often work across Sydney, Melbourne, and Brisbane. Stable module contracts reduce merge friction between locations, while shared handling of currency, tax, and time zones keeps local and cloud environments consistent.

Plan module boundaries first

Start with business boundaries rather than package names. A common design has a domain module for entities and value objects, an API module for contracts and DTOs, and an application module containing the runnable Spring Boot service. Infrastructure concerns can join later when they justify a separate module.

Draw dependencies as arrows before creating POMs. The application may depend on the domain and API modules, while reusable modules should never depend back on the executable. This one-way arrangement prevents cycles and keeps unit tests fast.

Choose module names that describe capabilities, such as billing-domain or customer-api, instead of generic labels like common or utilities. A focused module has one owner, a clear reason to change, and a public surface that other teams can understand.

Create the parent aggregator

Create the root directory and add a parent pom.xml with pom packaging. The aggregator lists child directories so Maven can determine reactor order. Spring Boot’s parent supplies sensible defaults, including dependency and plugin versions.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.5</version>
        <relativePath/>
    </parent>

    <groupId>com.javawhizz.example</groupId>
    <artifactId>customer-platform</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <properties>
        <java.version>21</java.version>
    </properties>

    <modules>
        <module>billing-domain</module>
        <module>customer-api</module>
        <module>application</module>
    </modules>
</project>

Every child inherits the group identifier, version, and dependency management. A relativePath of ../pom.xml lets Maven locate that parent, while the empty element stops Maven from searching beyond the project for an external parent.

Run mvn validate to confirm the reactor structure. Keep business dependencies in child POMs; the aggregator should coordinate builds rather than become a bucket for every library.

Implement a reusable domain module

The domain module should express business rules without Spring annotations where practical. Keeping it plain Java allows other services to reuse it and makes domain tests run without starting an application context.

package com.javawhizz.example.billing;

import java.math.BigDecimal;
import java.util.Currency;

public record Money(BigDecimal amount, Currency currency) {
    public Money {
        if (amount == null || amount.signum() < 0 || currency == null) {
            throw new IllegalArgumentException("Invalid monetary amount");
        }
    }
}

Use ISO 4217 currency codes and BigDecimal for monetary values. The record validates basic inputs, while constructors or domain methods can enforce stricter rules such as supported currencies, payment limits, or rounding policies.

Place persistence mappings in a separate adapter module when entities need JPA. If entities remain in the domain module, add the Jakarta Persistence dependency deliberately and document that boundary so database concerns do not spread across the codebase.

Wire modules into the executable

The runnable module depends on libraries using their Maven coordinates. Maven discovers sibling modules through the reactor, so a local verification does not require an internal artifact to exist in a remote repository.

<dependencies>
    <dependency>
        <groupId>com.javawhizz.example</groupId>
        <artifactId>billing-domain</artifactId>
        <version>${project.version}</version>
    </dependency>

    <dependency>
        <groupId>com.javawhizz.example</groupId>
        <artifactId>customer-api</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Declare each internal dependency once and avoid duplicating versions across modules. When several modules share third-party libraries, manage those versions in the parent’s dependencyManagement section.

Add the Spring Boot plugin only to the executable module. Its repackage goal creates an executable JAR, whereas library modules should produce ordinary JAR files. Place the @SpringBootApplication class in a package that covers the application’s components, or configure scanBasePackages deliberately.

Test and package the reactor

Each module should own its unit tests, while the application module can include integration tests using @SpringBootTest. Testcontainers is useful for PostgreSQL checks because it creates disposable instances instead of relying on a developer’s local database.

mvn clean verify
mvn -pl application -am package

The first command tests every module and fails the reactor when verification fails. The second builds the application together with its required upstream modules, allowing teams to produce the boot JAR without processing unrelated modules.

After verification passes, run the artifact with java -jar application/target/application-0.1.0-SNAPSHOT.jar. A CI pipeline should cache the local Maven repository, archive test reports, and publish the executable JAR only after every required check succeeds.

Prepare for Australian production use

Production configuration belongs outside the packaged artifacts. Supply database URLs, OAuth client settings, and payment-gateway credentials through environment variables or a managed vault. For Australian deployments, select the intended cloud region, such as AWS Sydney or Azure Australia East, and define failover behaviour explicitly.

Consumer-facing modules need Australian business conventions. Store money with BigDecimal and Currency, present prices in AUD, and state whether the displayed amount includes the 10% GST. Use unambiguous day-month-year text or ISO values, with IANA time zones such as Australia/Sydney or Australia/Brisbane.

JavaWhizz supports teams needing adjacent frontend work through its Spring Boot web development service, including integration between Java APIs and customer-facing systems. Across that work, clear module boundaries, automated reactor builds, and environment-specific configuration keep releases consistent and maintainable.