GH-1287 - Support for runtime application module verification.

The spring-modulith-runtime artifact now exposes a `spring.modulith.runtime.verification-enabled` property to initiate application module arrangement verification on application startup. The ApplicationModules instance is bootstrapped asynchronously and any failure is elevated onto the main application thread in the post-singleton-initialization phase. We also register a FailureAnalyzer implementation to give a bit of additional guidance on how to deal with the problem.

Author: odrotbohm

spring-modulith-runtime/pom.xml

@@ -68,6 +68,12 @@
 			<scope>test</scope>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-configuration-processor</artifactId>
+			<optional>true</optional>
+		</dependency>
+
 	</dependencies>
 
 	<build>

spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/autoconfigure/FailedModuleVerificationFailureAnalyzer.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.runtime.autoconfigure;
+
+import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
+import org.springframework.boot.diagnostics.FailureAnalysis;
+import org.springframework.modulith.core.Violations;
+
+/**
+ * A {@link org.springframework.boot.diagnostics.FailureAnalyzer} to give explanation what's wrong when a runtime
+ * application module verification fails.
+ *
+ * @author Oliver Drotbohm
+ * @since 2.0
+ * @soundtrack Martin Kohlstedt - ZIN (Flur)
+ */
+class FailedModuleVerificationFailureAnalyzer extends AbstractFailureAnalyzer<Violations> {
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.boot.diagnostics.AbstractFailureAnalyzer#analyze(java.lang.Throwable, java.lang.Throwable)
+	 */
+	@Override
+	protected FailureAnalysis analyze(Throwable rootFailure, Violations cause) {
+
+		var description = """
+				Spring Modulith application module verification was enabled and failed! The following violations were detected:
+
+				%s
+				""".formatted(cause.getMessage());
+
+		var action = """
+				Please fix the architectural violations or disable the runtime verification by setting spring.modulith.runtime.verification-enabled to false or removing it entirely.
+				""";
+
+		return new FailureAnalysis(description, action, cause);
+	}
+}

spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/autoconfigure/SpringModulithRuntimeAutoConfiguration.java

@@ -15,34 +15,43 @@
  */
 package org.springframework.modulith.runtime.autoconfigure;
 
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executor;
+import java.util.function.Supplier;
+
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.BeanFactoryInitializer;
+import org.springframework.beans.factory.ListableBeanFactory;
 import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.SmartInitializingSingleton;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.beans.factory.config.BeanDefinition;
+import org.springframework.beans.factory.config.ConfigurableBeanFactory;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingClass;
 import org.springframework.boot.context.event.ApplicationStartedEvent;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationListener;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Lazy;
 import org.springframework.context.annotation.Role;
 import org.springframework.core.io.Resource;
 import org.springframework.core.io.support.SpringFactoriesLoader;
-import org.springframework.core.task.AsyncTaskExecutor;
-import org.springframework.core.task.SimpleAsyncTaskExecutor;
 import org.springframework.modulith.ApplicationModuleInitializer;
 import org.springframework.modulith.core.ApplicationModule;
 import org.springframework.modulith.core.ApplicationModuleIdentifiers;
 import org.springframework.modulith.core.ApplicationModules;
 import org.springframework.modulith.core.ApplicationModulesFactory;
+import org.springframework.modulith.core.VerificationOptions;
 import org.springframework.modulith.core.util.ApplicationModulesExporter;
 import org.springframework.modulith.runtime.ApplicationModulesRuntime;
 import org.springframework.modulith.runtime.ApplicationRuntime;
-import org.springframework.util.function.ThrowingSupplier;
 
 /**
  * Auto-configuration to register an {@link ApplicationRuntime}, a {@link ApplicationModulesRuntime} and an
@@ -51,9 +60,10 @@
  * @author Oliver Drotbohm
  */
 @AutoConfiguration
+@EnableConfigurationProperties(SpringModulithRuntimeProperties.class)
 class SpringModulithRuntimeAutoConfiguration {
 
-	private static final AsyncTaskExecutor EXECUTOR = new SimpleAsyncTaskExecutor();
+	private static final Logger LOG = LoggerFactory.getLogger(SpringModulithRuntimeAutoConfiguration.class);
 
 	@Bean
 	@Lazy
@@ -67,13 +77,17 @@ static ApplicationRuntime modulithsApplicationRuntime(ApplicationContext context
 	@Lazy
 	@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
 	@ConditionalOnMissingBean
-	static ApplicationModulesRuntime modulesRuntime(ApplicationRuntime runtime) {
-
-		ThrowingSupplier<ApplicationModules> modules = () -> EXECUTOR
-				.submit(() -> ApplicationModulesBootstrap.initializeApplicationModules(runtime.getMainApplicationClass()))
-				.get();
+	static ApplicationModulesRuntime modulesRuntime(ApplicationModulesBootstrap bootstrap, ApplicationRuntime runtime) {
+		return new ApplicationModulesRuntime(() -> bootstrap.getApplicationModules().join(), runtime);
+	}
 
-		return new ApplicationModulesRuntime(modules, runtime);
+	@Bean
+	@Lazy
+	@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
+	@ConditionalOnMissingBean
+	static ApplicationModulesBootstrap applicationModulesInitializer(ApplicationRuntime runtime,
+			ConfigurableBeanFactory factory) {
+		return new ApplicationModulesBootstrap(runtime.getMainApplicationClass(), factory.getBootstrapExecutor());
 	}
 
 	@Bean
@@ -84,6 +98,15 @@ static ApplicationListener<ApplicationStartedEvent> applicationModuleInitializin
 		return __ -> invoker.invokeInitializers(initializers.stream());
 	}
 
+	@Bean
+	@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
+	@ConditionalOnBooleanProperty(value = "spring.modulith.runtime.verification-enabled", matchIfMissing = false)
+	static RuntimeApplicationModuleVerifier applicationModuleVerifier(ApplicationModulesBootstrap bootstrap,
+			ObjectProvider<VerificationOptions> verification) {
+
+		return new RuntimeApplicationModuleVerifier(bootstrap.getApplicationModules(), verification);
+	}
+
 	/**
 	 * {@link ApplicationModuleMetadata} obtained from the Spring Modulith metadata located at
 	 * {@value ApplicationModulesExporter#DEFAULT_LOCATION}.
@@ -119,11 +142,13 @@ ApplicationModuleIdentifiers applicationModuleIdentifiers(ApplicationModuleMetad
 				: ApplicationModuleIdentifiers.of(runtime.getObject().get());
 	}
 
-	private static class ApplicationModulesBootstrap {
+	static class ApplicationModulesBootstrap {
 
 		private static final Logger LOGGER = LoggerFactory.getLogger(ApplicationModulesBootstrap.class);
 		private static final ApplicationModulesFactory BOOTSTRAP;
 
+		private final CompletableFuture<ApplicationModules> modules;
+
 		static {
 
 			var factories = SpringFactoriesLoader.loadFactories(ApplicationModulesFactory.class,
@@ -132,6 +157,19 @@ private static class ApplicationModulesBootstrap {
 			BOOTSTRAP = !factories.isEmpty() ? factories.get(0) : ApplicationModulesFactory.defaultFactory();
 		}
 
+		ApplicationModulesBootstrap(Class<?> applicationMainClass, @Nullable Executor executor) {
+
+			Supplier<ApplicationModules> supplier = () -> initializeApplicationModules(applicationMainClass);
+
+			this.modules = executor == null
+					? CompletableFuture.supplyAsync(supplier)
+					: CompletableFuture.supplyAsync(supplier, executor);
+		}
+
+		CompletableFuture<ApplicationModules> getApplicationModules() {
+			return modules;
+		}
+
 		static ApplicationModules initializeApplicationModules(Class<?> applicationMainClass) {
 
 			LOGGER.debug("Obtaining Spring Modulith application modules…");
@@ -171,4 +209,36 @@ static class ArchUnitRuntimeDependencyMissingConfiguration {
 			throw new MissingRuntimeDependency(DESCRIPTION, SUGGESTED_ACTION);
 		}
 	}
+
+	/**
+	 * A component to verify the application module arrangement at runtime.
+	 *
+	 * @author Oliver Drotbohm
+	 * @since 2.0
+	 */
+	static class RuntimeApplicationModuleVerifier
+			implements BeanFactoryInitializer<ListableBeanFactory>, SmartInitializingSingleton {
+
+		private final CompletableFuture<Void> modules;
+
+		RuntimeApplicationModuleVerifier(CompletableFuture<ApplicationModules> modules,
+				ObjectProvider<VerificationOptions> verification) {
+
+			this.modules = modules.thenAccept(it -> {
+				it.verify(verification.getIfAvailable(VerificationOptions::defaults));
+				LOG.info("Spring Modulith application module verification completed successfully.");
+			});
+		}
+
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.beans.factory.SmartInitializingSingleton#afterSingletonsInstantiated()
+		 */
+		@Override
+		public void afterSingletonsInstantiated() {
+			modules.join();
+		}
+
+		public void initialize(ListableBeanFactory beanFactory) {};
+	}
 }

spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/autoconfigure/SpringModulithRuntimeProperties.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.runtime.autoconfigure;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.boot.context.properties.bind.ConstructorBinding;
+import org.springframework.boot.context.properties.bind.DefaultValue;
+
+/**
+ * Configuration properties for Spring modulith's runtime support.
+ *
+ * @author Oliver Drotbohm
+ * @since 2.0
+ * @soundtrack Phil Siemers - Was wenn doch (Was wenn doch)
+ */
+@ConfigurationProperties("spring.modulith.runtime")
+class SpringModulithRuntimeProperties {
+
+	/**
+	 * Whether the application modules arrangement is supposed to be verified on startup. Defaults to {@literal false}.
+	 */
+	private final boolean verificationEnabled;
+
+	@ConstructorBinding
+	SpringModulithRuntimeProperties(@DefaultValue("false") boolean verificationEnabled) {
+		this.verificationEnabled = verificationEnabled;
+	}
+
+	public boolean isVerificationEnabled() {
+		return verificationEnabled;
+	}
+}

spring-modulith-runtime/src/main/resources/META-INF/spring.factories

@@ -1,3 +1,4 @@
 # Failure analyzers
 org.springframework.boot.diagnostics.FailureAnalyzer=\
-org.springframework.modulith.runtime.autoconfigure.MissingRuntimeDependencyFailureAnalyzer
+  org.springframework.modulith.runtime.autoconfigure.MissingRuntimeDependencyFailureAnalyzer,\
+  org.springframework.modulith.runtime.autoconfigure.FailedModuleVerificationFailureAnalyzer

spring-modulith-runtime/src/test/java/org/springframework/modulith/runtime/autoconfigure/SpringModulithRuntimeAutoConfigurationIntegrationTests.java

@@ -44,6 +44,8 @@
 import org.springframework.modulith.core.util.ApplicationModulesExporter;
 import org.springframework.modulith.runtime.ApplicationModulesRuntime;
 import org.springframework.modulith.runtime.ApplicationRuntime;
+import org.springframework.modulith.runtime.autoconfigure.SpringModulithRuntimeAutoConfiguration.ApplicationModulesBootstrap;
+import org.springframework.modulith.runtime.autoconfigure.SpringModulithRuntimeAutoConfiguration.RuntimeApplicationModuleVerifier;
 
 import com.tngtech.archunit.core.importer.ClassFileImporter;
 
@@ -72,8 +74,8 @@ void bootstrapRegistersRuntimeInstances() {
 
 		runner.withUserConfiguration(SampleApp.class)
 				.run(context -> {
-					assertThat(context.getBean(ApplicationRuntime.class)).isNotNull();
-					assertThat(context.getBean(ApplicationModulesRuntime.class)).isNotNull();
+					assertThat(context).hasSingleBean(ApplicationRuntime.class);
+					assertThat(context).hasSingleBean(ApplicationModulesRuntime.class);
 				});
 	}
 
@@ -160,6 +162,27 @@ void registersApplicationModuleIdentifiersWithoutInstantiatingApplicationModules
 				});
 	}
 
+	@Test // GH-1287
+	void doesNotActivateVerifyingListenerByDefault() {
+
+		runner.run(context -> {
+			assertThat(context).hasSingleBean(SpringModulithRuntimeProperties.class);
+			assertThat(context).doesNotHaveBean(RuntimeApplicationModuleVerifier.class);
+			tracker.assertBeanNotInitialized(ApplicationModulesBootstrap.class);
+		});
+	}
+
+	@Test // GH-1287
+	void registersVerifyingApplicationListenerIfConfigured() {
+
+		runner.withUserConfiguration(SampleApp.class)
+				.withPropertyValues("spring.modulith.runtime.verification-enabled=true")
+				.run(context -> {
+					assertThat(context).hasSingleBean(RuntimeApplicationModuleVerifier.class);
+					tracker.assertBeanInitialized(ApplicationModulesBootstrap.class);
+				});
+	}
+
 	static class InitializationTracker implements BeanPostProcessor, BeanFactoryAware {
 
 		private final Map<String, Class<?>> initializedBeans = new HashMap<>();

src/docs/antora/modules/ROOT/pages/appendix.adoc

@@ -122,6 +122,10 @@ Usually not recommended in multi-instance deployments as other instances might s
 |`false`
 |Deprecated as of 1.3. Prefer `spring.modulith.events.republish-outstanding-events-on-restart`.
 
+|`spring.modulith.runtime.verification-enabled`
+|`false`
+|Whether to verify the application module arrangement during application startup. Requires the `spring-modulith-runtime` artifact on the classpath. For more information, see xref:runtime.adoc#setup[the section on Spring Modulith's runtime support] for details.
+
 |`spring.modulith.test.file-modification-detector`
 |none
 |This can either be one of the predefined values `uncommitted-changes`, `reference-commit`, `default` or the fully-qualified class name of a `FileModificationDetector` that will be used to inspect which files of the projects have been changed.

src/docs/antora/modules/ROOT/pages/runtime.adoc

@@ -39,6 +39,7 @@ Adding this JAR will cause Spring Boot auto-configuration to run that registers
 
 * An `ApplicationModulesRuntime` that allows to access the `ApplicationModules`.
 * A `SpringBootApplicationRuntime` to back the former bean to detect the main application class.
+* A `RuntimeApplicationModuleVerifier` to verify the application module arrangement on startup and abort it if violations are detected, only if `spring.modulith.runtime.verification-enabled` is configured to `true`.
 * An event listener for https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.spring-application.application-events-and-listeners[`ApplicationStartedEvent`]s that will invoke xref:runtime.adoc#application-module-initializer[`ApplicationModuleInitializer`] beans defined in the application context.
 
 [[application-module-initializer]]