Structuring Maven Multi‑Module Projects and Building a Common Framework for Backend Services

This article, part of a series on building foundational infrastructure, introduces the need to divide a Spring Boot project into multiple Maven modules when business logic becomes complex, moving from a single‑module "short‑fast" structure to a modular architecture.

It describes the drawbacks of a monolithic module, such as duplicated utility code across projects, and proposes extracting shared utilities into a dedicated common‑frame project that all business modules can depend on.

The guide then details how to partition the common framework into specific Maven modules:

Maven Module

Module Definition

Special Notes

api

Defines service provider interfaces, OpenFeign contracts, data transfer objects, and enums.

Can be omitted for a monolithic service.

base

Contains generic utilities and common configuration.

rpc

Implements the OpenFeign interfaces from the api module; can be merged with api if preferred.

Can be omitted for a monolithic service.

service

Houses business logic; typically the largest module.

interaction

Handles user‑facing layers such as controllers, MQ listeners, and OpenFeign client implementations.

start

Contains the application entry point, configuration files, and global logging settings.

After cloning the common‑frame demo repository, the reader should run mvn clean install to install the common‑dependency package into the local Maven repository.

For optional auto‑configuration, the article recommends using Spring's @ConditionalOnProperty annotation, allowing each module to enable or disable specific configurations as needed.

In summary, the article outlines three key points: the limitations of a single module as business complexity grows, the drawbacks of a single project with many business modules, and the benefits of extracting a common framework with a clear multi‑module structure to keep business code focused.

Finally, it shows the complete Maven dependency hierarchy for the first part of the series, linking back to the author's introductory book "Deep Dive into DDD".