Introduction

Multi-module Spring Boot systems are common in enterprise codebases. You might keep domain entities in one JAR, service logic in another, and API adapters in a third. This structure improves reuse, but it also introduces a frequent problem: components in dependency modules are present on the classpath yet never instantiated because scan boundaries are wrong.

Spring Boot starts component scanning from the package containing your @SpringBootApplication class. If other modules live outside that package tree, beans are skipped unless you configure scanning explicitly. This article shows reliable patterns for scanning components across Maven modules and dependency JARs without making startup behavior fragile.

Core Sections

1) Place the main class at a stable package root

The simplest option is to keep the application class in a common root package that naturally includes all modules.

1package com.acme.app;
2
3import org.springframework.boot.SpringApplication;
4import org.springframework.boot.autoconfigure.SpringBootApplication;
5
6@SpringBootApplication
7public class BillingApplication {
8    public static void main(String[] args) {
9        SpringApplication.run(BillingApplication.class, args);
10    }
11}

If your module packages are com.acme.app.core, com.acme.app.data, and com.acme.app.web, default scanning usually just works.

2) Use scanBasePackages when package roots differ

If modules use separate roots, declare them explicitly.

1@SpringBootApplication(scanBasePackages = {
2    "com.acme.billing.api",
3    "org.shared.platform.services",
4    "org.shared.platform.repositories"
5})
6public class BillingApplication {}

This is straightforward and transparent, but keep the list small and intentional. Overly broad scan paths can increase startup time and accidentally register test or legacy beans.

3) Combine component scanning with repository/entity config

Cross-module setups often need JPA scanning too, not just @Component discovery.

1import org.springframework.boot.autoconfigure.domain.EntityScan;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
4
5@Configuration
6@EntityScan(basePackages = "org.shared.platform.domain")
7@EnableJpaRepositories(basePackages = "org.shared.platform.repositories")
8class PersistenceConfig {}

Without @EntityScan and @EnableJpaRepositories, you may get runtime errors where services are found but repositories or entities are not.

4) Maven dependency hygiene matters

Scanning cannot discover classes from modules that are missing from runtime dependencies.

1<dependency>
2  <groupId>org.shared</groupId>
3  <artifactId>platform-services</artifactId>
4  <version>${platform.version}</version>
5</dependency>

Confirm each module is on the application classpath in the effective POM and in the final packaged artifact. Optional or test-scoped dependencies are common causes of "works in IDE, fails in deployment" behavior.

5) Debug scan failures quickly

When beans are missing, enable startup diagnostics and verify candidates.

logging.level.org.springframework.context.annotation=DEBUG
logging.level.org.springframework.beans.factory.support=INFO

Then run a smoke test that loads the context and asserts critical beans are present. Catching scan regressions in CI is far cheaper than debugging failed deployment startups.

6) Production checklist for cross-module Spring component scanning

Before shipping this approach in a real project, validate it in a controlled workflow that mirrors production traffic, data shape, and failure modes. Start with one measurable success metric such as latency, error rate, or precision, then define acceptable limits. Run the implementation with representative inputs, not toy samples, and collect logs that explain both successes and failures. If behavior depends on external services or user input, include at least one negative test path so you can confirm how the system reacts when assumptions are violated.

Next, create an operational checklist for rollout. Document required configuration values, version constraints, and environment variables in one place. Add a lightweight smoke test that can run in CI and after deployment. Decide who owns alerts and what threshold should trigger investigation. For high-impact systems, define a rollback switch or feature flag so you can disable the new behavior without a full release cycle.

Finally, capture maintenance notes that future contributors will need: edge cases, known limitations, and links to test fixtures. This short documentation step reduces regressions during refactors and keeps the implementation understandable after the original author rotates to another project.

Common Pitfalls

• Assuming Boot scans all dependencies automatically regardless of package location.
• Configuring @ComponentScan but forgetting matching JPA entity and repository scanning.
• Using overly broad scan packages that register unintended classes and slow startup.
• Declaring shared modules with the wrong Maven scope so classes are absent at runtime.
• Relying only on manual testing instead of context-load tests that detect scan regressions.

Summary

Component scanning across Maven modules and JARs is predictable once package boundaries and runtime dependencies are explicit. Start with sensible package layout, then add targeted scanBasePackages, @EntityScan, and @EnableJpaRepositories where needed. Back this with context-load tests and logging for diagnostics. With these controls, multi-module Spring Boot applications remain modular without sacrificing startup reliability.