feat(arch): Per-module Spring dependencies and conditional app wiring

* Bump generated Spring Boot to 4.1.0
* Replace blanket spring-context with role-specific Spring Boot starters per module; common-domain carries the core starter that plain modules inherit transitively
* Presentation modules: spring-boot-starter-web (rest), spring-boot-starter-graphql (graphql)
* Integration modules: spring-boot-starter-data-jpa (database), spring-boot-starter-restclient (rest client), spring-boot-starter-graphql (graphql)
* Make app's web/data-jpa starters and AppServletInitializer/@EnableTransactionManagement conditional on a rest presentation / database integration

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01McmUDzyMrkYpbyeU5UWrot

Author: jeffjensen

src/main/resources/META-INF/archetype-post-generate.groovy

@@ -201,16 +201,60 @@ def projectDir = new File(request.outputDirectory)
 def subDir     = new File(projectDir, artifactId)
 if (subDir.isDirectory()) projectDir = subDir
 
+// ─── Spring dependency selection ──────────────────────────────────────────────
+// Each composed module declares the most specific Spring Boot starter that is useful
+// for its role rather than a blanket low-level dependency. common-domain (which every
+// other module depends on) carries the core spring-boot-starter, so the "plain" modules
+// — domain-* and the service modules — inherit the @Configuration / @ComponentScan API
+// transitively and declare no Spring dependency of their own. Presentation (server-side)
+// and integration (client-side) modules add a role-specific starter on top: a 'rest'
+// presentation serves endpoints via spring-boot-starter-web, while a 'rest' integration
+// consumes an external API via spring-boot-starter-restclient (no servlet web stack). All
+// gated on includeSpring; with Spring off no module references Spring at all.
+
+def STARTER            = [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter']
+def STARTER_WEB        = [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-web']
+def STARTER_DATA_JPA   = [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-data-jpa']
+def STARTER_GRAPHQL    = [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-graphql']
+def STARTER_RESTCLIENT = [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-restclient']
+
+/** Role-specific starter for an integration (client-side) module, or null when none fits
+ *  (those modules rely on the core starter inherited transitively via common-domain). */
+def integrationStarter = { String type ->
+    switch (type?.trim()?.toLowerCase()) {
+        case 'database': return STARTER_DATA_JPA
+        case 'rest':     return STARTER_RESTCLIENT   // consumes an external REST API; no servlet web stack
+        case 'graphql':  return STARTER_GRAPHQL
+        default:         return null
+    }
+}
+
+/** Role-specific starter for a presentation (server-side) module, or null when none fits. */
+def presentationStarter = { String type ->
+    switch (type?.trim()?.toLowerCase()) {
+        case 'rest':     return STARTER_WEB          // serves REST endpoints over servlet MVC
+        case 'graphql':  return STARTER_GRAPHQL
+        default:         return null
+    }
+}
+
+/** Wraps a resolved starter into a module deps list: a one-element list when Spring is on
+ *  and a starter was resolved, otherwise empty. */
+def starterDeps = { starter ->
+    (includeSpring && starter) ? [starter] : []
+}
+
+// common-domain's own Spring dependency: the core starter, which provides the
+// @Configuration API to every dependent module transitively (empty when Spring is off).
+def commonSpring = includeSpring ? [STARTER] : []
+
 // ─── Spring configuration class generator ─────────────────────────────────────
 // When includeSpring is true, every module the app composes carries a @Configuration
-// class in its `.config` sub-package (the app's Application class @Imports them all)
-// and declares spring-context. The module root package also gets a marker
-// "{Module}ComponentScan" interface that the @Configuration targets via
-// @ComponentScan(basePackageClasses=…) — a type-safe anchor for scanning the whole
-// module. Everything here is skipped when includeSpring is false.
-
-def SPRING_CONTEXT = [groupId: 'org.springframework', artifactId: 'spring-context']
-def springCtx = includeSpring ? [SPRING_CONTEXT] : []   // appended to module deps only when Spring is enabled
+// class in its `.config` sub-package (the app's Application class @Imports them all).
+// The module root package also gets a marker "{Module}ComponentScan" interface that the
+// @Configuration targets via @ComponentScan(basePackageClasses=…) — a type-safe anchor
+// for scanning the whole module. Skipped entirely when includeSpring is false.
+
 def configFqns = []
 
 /** Writes a {Module}ComponentScan marker interface into the module root package and a
@@ -279,7 +323,7 @@ def parentInherit = includeSpring ? """\
   <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
-    <version>4.0.6</version>
+    <version>4.1.0</version>
     <relativePath/>
   </parent>
 
@@ -485,7 +529,7 @@ writeFile(projectDir, 'common-domain/pom.xml',
     modulePom(groupId, artifactId, version,
         'common-domain',
         'Domain classes common to all modules.',
-        springCtx))
+        commonSpring))
 srcTree(projectDir, 'common-domain', pkgPath,
     ['common/domain'], ['common/domain'],
     'Domain classes common to all modules.')
@@ -515,7 +559,7 @@ integrations.each { intg ->
         modulePom(groupId, artifactId, version,
             domMod,
             "Domain classes for the ${intg.name} ${disp} data source.",
-            ['common-domain'] + springCtx))
+            ['common-domain']))
     srcTree(projectDir, domMod, pkgPath,
         [domSub], [domSub],
         "Domain classes for the ${intg.name} ${disp} integration.")
@@ -525,7 +569,7 @@ integrations.each { intg ->
         modulePom(groupId, artifactId, version,
             implMod,
             "Integration classes (DAOs, repositories) for the ${intg.name} ${disp} data source.",
-            ['common-domain', domMod] + springCtx,
+            ['common-domain', domMod] + starterDeps(integrationStarter(intg.rawType)),
             failsafeSection))
     srcTree(projectDir, implMod, pkgPath,
         [implSub], [implSub],
@@ -551,15 +595,15 @@ serviceModules.each { svcMod ->
     writeFile(projectDir, "${domMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             domMod, domDesc,
-            ['common-domain'] + springCtx))
+            ['common-domain']))
     srcTree(projectDir, domMod, pkgPath, [domPkg], [domPkg], domDesc)
     configClass(domMod, domPkg)
 
     // Business logic, depending on its own service-area domain module.
     writeFile(projectDir, "${svcMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             svcMod, svcDesc,
-            ['common-domain', domMod] + springCtx))
+            ['common-domain', domMod]))
     srcTree(projectDir, svcMod, pkgPath, [svcPkg], [svcPkg], svcDesc)
     configClass(svcMod, svcPkg)
 }
@@ -575,7 +619,7 @@ presentations.each { pType ->
         modulePom(groupId, artifactId, version,
             domMod,
             "Domain classes for the ${disp} presentation tier.",
-            ['common-domain'] + springCtx))
+            ['common-domain']))
     srcTree(projectDir, domMod, pkgPath,
         ["domain/${pType}"], ["domain/${pType}"],
         "Domain classes for the ${disp} presentation tier.")
@@ -585,7 +629,7 @@ presentations.each { pType ->
         modulePom(groupId, artifactId, version,
             implMod,
             "Request-handling classes (controllers) for the ${disp} presentation tier.",
-            ['common-domain', domMod] + springCtx))
+            ['common-domain', domMod] + starterDeps(presentationStarter(pType))))
     srcTree(projectDir, implMod, pkgPath,
         ["presentation/${pType}"], ["presentation/${pType}"],
         "Request-handling classes for the ${disp} presentation tier.")
@@ -594,10 +638,19 @@ presentations.each { pType ->
 
 // ─── app ─────────────────────────────────────────────────────────────────────
 
-def appStarters = includeSpring ? [
-    [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-web'],
-    [groupId: 'org.springframework.boot', artifactId: 'spring-boot-starter-data-jpa'],
-] : []
+// The app declares the web / data-jpa starters only when its composition warrants them, and
+// inherits whatever else its composed modules bring. A 'rest' presentation makes it a servlet
+// web app (so it also gets the WAR-deployment AppServletInitializer); a 'database' integration
+// gives it JPA + transactions (so Application carries @EnableTransactionManagement, which needs
+// spring-tx from spring-boot-starter-data-jpa). All gated on includeSpring.
+def hasRestPresentation    = presentations.contains('rest')
+def hasDatabaseIntegration = integrations.any { it.rawType == 'database' }
+
+def appStarters = []
+if (includeSpring) {
+    if (hasRestPresentation)    appStarters << STARTER_WEB
+    if (hasDatabaseIntegration) appStarters << STARTER_DATA_JPA
+}
 writeFile(projectDir, 'app/pom.xml',
     modulePom(groupId, artifactId, version,
         'app',
@@ -611,22 +664,24 @@ if (includeSpring) {
 // module's @Configuration class so the whole tree is assembled into one context.
 def appConfigPkg = (pkgPath + '/app/config').replace('/', '.')
 def importsBlock = configFqns.sort().collect { "    ${it}.class," }.join('\n')
+// @EnableTransactionManagement requires spring-tx (pulled in by spring-boot-starter-data-jpa),
+// so it is only emitted when a database integration puts that starter on the app's classpath.
+def txImport     = hasDatabaseIntegration ? 'import org.springframework.transaction.annotation.EnableTransactionManagement;\n' : ''
+def txAnnotation = hasDatabaseIntegration ? '@EnableTransactionManagement\n' : ''
 writeFile(projectDir, "app/src/main/java/${pkgPath}/app/config/Application.java", """\
 package ${appConfigPkg};
 
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.context.annotation.Import;
-import org.springframework.transaction.annotation.EnableTransactionManagement;
-
+${txImport}
 /**
  * Spring Boot main application class for running standalone in Boot configured embedded container. Not used with WAR
  * deployment.
  */
 @SpringBootApplication
-@EnableTransactionManagement
-@Import({
+${txAnnotation}@Import({
 ${importsBlock}
 })
 public class Application {
@@ -635,6 +690,9 @@ public class Application {
     }
 }
 """)
+// AppServletInitializer extends SpringBootServletInitializer (a servlet web stack), so it is
+// only generated when a 'rest' presentation makes the app a servlet web application.
+if (hasRestPresentation) {
 writeFile(projectDir, "app/src/main/java/${pkgPath}/app/config/AppServletInitializer.java", """\
 package ${appConfigPkg};
 
@@ -657,6 +715,7 @@ public class AppServletInitializer extends SpringBootServletInitializer {
 }
 """)
 }
+}
 
 // ─── acceptance-tests ─────────────────────────────────────────────────────────
 

src/main/resources/META-INF/maven/archetype-metadata.xml

@@ -60,8 +60,11 @@
       <defaultValue>true</defaultValue>
       <!-- true (default): generate the Spring Boot wiring — parent inherits
            spring-boot-starter-parent, every app-composed module gets a @Configuration
-           class and spring-context, and app gets the Application / AppServletInitializer
-           classes plus the web and data-jpa starters.
+           class plus the Spring Boot starter suited to its role (common-domain carries
+           the core spring-boot-starter that the plain modules inherit transitively), and
+           app gets the Application class plus the role starters and entry-point classes its
+           composition calls for (web + AppServletInitializer for a rest presentation,
+           data-jpa + @EnableTransactionManagement for a database integration).
            false: omit all Spring artifacts (configs, classes, and pom items). -->
     </requiredProperty>
 

src/site/asciidoc/modules.adoc

@@ -41,9 +41,10 @@ _Depends on_: `common-domain`
 
 `app`::
 Application assembly — produces the runnable artifact (e.g. Spring Boot über-jar).
-Contains the Spring Boot `Application` (`@SpringBootApplication`) and `AppServletInitializer`
-(WAR deployment) classes in `{base.package}.app.config`, and adds the
-`spring-boot-starter-web` and `spring-boot-starter-data-jpa` dependencies.
+Contains the Spring Boot `Application` (`@SpringBootApplication`) class in
+`{base.package}.app.config`, and adds the role starters its composition calls for — a `rest`
+presentation adds `spring-boot-starter-web` and an `AppServletInitializer` (WAR deployment)
+class; a `database` integration adds `spring-boot-starter-data-jpa` and `@EnableTransactionManagement`.
 +
 _Package_: `{base.package}.app`, `{base.package}.app.config` +
 _Depends on_: all non-test modules (`common-domain`, all domain and integration modules,
@@ -101,7 +102,7 @@ There is no `pom.xml` at the project root — `parent/` is a sibling of all othe
 
 It contains:
 
-* `<parent>` — inherits `spring-boot-starter-parent` (4.0.6) via an empty `<relativePath/>`, supplying Spring dependency management and plugin defaults
+* `<parent>` — inherits `spring-boot-starter-parent` (4.1.0) via an empty `<relativePath/>`, supplying Spring dependency management and plugin defaults
 * `<packaging>pom</packaging>`
 * `<modules>` — all sibling modules referenced as `../module` relative paths, sorted alphabetically
 * `<dependencyManagement>` — all modules pinned to `${project.version}`, sorted alphabetically by `artifactId`

src/site/asciidoc/requirements.adoc

@@ -48,9 +48,12 @@ Prompt for a comma-separated list of presentation-tier types
 Whether to generate the Spring Boot wiring.
 
 * `true` (default): the `parent/` POM inherits `spring-boot-starter-parent`, every
-  app-composed module carries a `@Configuration` class and `spring-context`, and `app`
-  gets the `Application` / `AppServletInitializer` classes plus the
-  `spring-boot-starter-web` and `spring-boot-starter-data-jpa` dependencies.
+  app-composed module carries a `@Configuration` class, and Spring Boot starters are
+  assigned per module by role — `common-domain` carries the core `spring-boot-starter`
+  that the plain `domain-*` and service modules inherit transitively. The `app` module
+  carries the `Application` class and adds the role starters its composition calls for: a
+  `rest` presentation adds `spring-boot-starter-web` and an `AppServletInitializer`; a
+  `database` integration adds `spring-boot-starter-data-jpa` and `@EnableTransactionManagement`.
 * `false`: omit all Spring artifacts — configs, classes, and POM items — producing a
   plain multi-module Java project with the same module structure.
 
@@ -66,7 +69,7 @@ Do not create a `pom.xml` at the project root.
   sorted alphabetically.
 * List every sibling module in `<dependencyManagement>` pinned to
   `${project.version}`, sorted alphabetically by `artifactId`.
-* Inherit `spring-boot-starter-parent` (version 4.0.6) as the parent POM — via `<parent>`
+* Inherit `spring-boot-starter-parent` (version 4.1.0) as the parent POM — via `<parent>`
   with an empty `<relativePath/>`, not a BOM import — so Spring artifact versions and
   sensible plugin defaults are managed centrally.
 * Properties: Java 21 via `maven.compiler.release`; UTF-8 source encoding via
@@ -134,11 +137,14 @@ For each presentation type, generate two modules
 
 Assembles the runnable artifact (e.g. Spring Boot uber jar).
 Depend on all generated modules except `acceptance-tests`, `common-testing`,
-and `app` itself, plus `spring-boot-starter-web` and `spring-boot-starter-data-jpa`.
-Contains the Spring Boot `Application` (`@SpringBootApplication`,
-`@EnableTransactionManagement`) and `AppServletInitializer` (WAR deployment)
-classes in the `.config` sub-package. `Application` `@Import`s the `@Configuration`
-class that every app-composed module carries in its own `.config` sub-package.
+and `app` itself. Add the role starters its composition calls for: `spring-boot-starter-web`
+when a `rest` presentation is present, `spring-boot-starter-data-jpa` when a `database`
+integration is present.
+Contains the Spring Boot `Application` (`@SpringBootApplication`) class in the `.config`
+sub-package, which `@Import`s the `@Configuration` class that every app-composed module
+carries in its own `.config` sub-package. `Application` additionally carries
+`@EnableTransactionManagement` when a `database` integration is present, and an
+`AppServletInitializer` (WAR deployment) class is generated when a `rest` presentation is present.
 
 === `acceptance-tests`
 

src/test/resources/projects/full/verify.groovy

@@ -234,9 +234,31 @@ assert cdConfig.contains("import ${p.replace('/', '.')}.common.domain.CommonDoma
 
 // parent imports the Spring Boot BOM; app pulls the starters
 assert parentPom.contains('<artifactId>spring-boot-starter-parent</artifactId>') : 'parent must inherit spring-boot-starter-parent'
+assert parentPom.contains('<version>4.1.0</version>')                            : 'parent must pin Spring Boot 4.1.0'
 assert appPom.contains('<artifactId>spring-boot-starter-web</artifactId>')    : 'app must depend on spring-boot-starter-web'
 assert appPom.contains('<artifactId>spring-boot-starter-data-jpa</artifactId>')   : 'app must depend on spring-boot-starter-data-jpa'
 
+// ── per-module Spring dependencies (#3): the blanket spring-context is gone; common-domain
+//    carries the core starter (so "plain" modules inherit @Configuration support transitively)
+//    and presentation/integration modules each declare a role-specific starter.
+modules.each { m ->
+    assert !text("${m}/pom.xml").contains('spring-context') : "${m} must not declare spring-context"
+}
+assert text('common-domain/pom.xml').contains('<artifactId>spring-boot-starter</artifactId>') \
+    : 'common-domain must carry the core spring-boot-starter (provides the @Configuration API transitively)'
+assert text('presentation-rest/pom.xml').contains('<artifactId>spring-boot-starter-web</artifactId>') \
+    : 'presentation-rest must declare spring-boot-starter-web'
+assert text('presentation-graphql/pom.xml').contains('<artifactId>spring-boot-starter-graphql</artifactId>') \
+    : 'presentation-graphql must declare spring-boot-starter-graphql (#2)'
+assert text('integration-db-users/pom.xml').contains('<artifactId>spring-boot-starter-data-jpa</artifactId>') \
+    : 'database integration must declare spring-boot-starter-data-jpa'
+assert text('integration-graphql-catalog/pom.xml').contains('<artifactId>spring-boot-starter-graphql</artifactId>') \
+    : 'graphql integration must declare spring-boot-starter-graphql'
+// plain domain/service modules declare no Spring dependency directly (inherited via common-domain)
+['domain-rest', 'domain-service-orders', 'service-orders'].each { m ->
+    assert !text("${m}/pom.xml").contains('org.springframework') : "${m} must not declare a Spring dependency directly"
+}
+
 // ── package-info Javadoc conventions (#2 test wording, #6 infrastructure, #7 GraphQL) ──
 
 assert text("common-domain/src/test/java/${p}/common/domain/package-info.java").contains('Tests for') \