feat(arch): Add per-service-area domain-service modules

Each service area now owns a dedicated domain module, separating its
business logic from its domain classes:

- For every `service` / `service-{name}` area, also generate a
  `domain-service` / `domain-service-{name}` module (package
  `{base.package}.domain.service[.{name}]`) that holds the area's domain
  classes and depends only on `common-domain`.
- The `service` / `service-{name}` module now depends on its own
  domain-service module in addition to `common-domain`.
- `acceptance-tests` depends on the new service-area domain modules
  alongside the integration and presentation domain modules.

This also refines the generated scaffold and its documentation:

- `common-testing` becomes shared test infrastructure and gains a
  `common/testing` package under src/test/java; `acceptance-tests` gains
  an `at` package under src/main/java.
- Add `typeDisplay` (e.g. GraphQL) and `lcFirst` helpers; normalize pom
  <description> and package-info Javadoc wording (trailing periods,
  display names) and prefix test-package Javadoc with "Tests for ...".
- Update the Maven site docs (modules.adoc, usage.adoc), requirements.adoc,
  and the affected verify.groovy assertions to match.

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

Author: jeffjensen

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

@@ -9,6 +9,17 @@ def typeAbbrev = { String t ->
     t.trim().toLowerCase() == 'database' ? 'db' : t.trim().toLowerCase()
 }
 
+/** Returns the human-readable display name used in prose (Javadoc, pom descriptions) for a type. */
+def typeDisplay = { String t ->
+    def s = t.trim().toLowerCase()
+    s == 'graphql' ? 'GraphQL' : s
+}
+
+/** Lower-cases the first character of a string, used to splice a description into a sentence. */
+def lcFirst = { String s ->
+    (s == null || s.isEmpty()) ? s : Character.toLowerCase(s.charAt(0)).toString() + s.substring(1)
+}
+
 def ensureDir = { File base, String rel ->
     // File(parent, child) normalises separators on all platforms
     new File(base, rel).mkdirs()
@@ -37,13 +48,15 @@ package ${fullPkg};
     }
     ensureDir(base, "${module}/src/main/resources")
     ensureDir(base, "${module}/src/test/java")
+    // Test-package Javadoc reuses the main wording, prefixed to mark it as the tests for that code.
+    def testDesc = 'Tests for ' + lcFirst(description.replaceAll(/\.\s*$/, '')) + '.'
     testSubs.each { sub ->
         def fullPkg = (pkgPath + '/' + sub).replace('/', '.')
         def dir = "${module}/src/test/java/${pkgPath}/${sub}"
         ensureDir(base, dir)
         writeFile(base, "${dir}/package-info.java", """\
 /**
- * ${description}
+ * ${testDesc}
  */
 package ${fullPkg};
 """)
@@ -149,21 +162,22 @@ def presentations = presentationTypesInput
 
 def intDomainMods  = integrations.collect  { "domain-${it.abbrev}-${it.name}" }
 def intImplMods    = integrations.collect  { "integration-${it.abbrev}-${it.name}" }
+def svcDomainMods  = serviceModules.collect { "domain-${it}" }
 def presDomainMods = presentations.collect { "domain-${it}" }
 def presImplMods   = presentations.collect { "presentation-${it}" }
 
 def allModules = (
     ['acceptance-tests', 'app', 'common-domain', 'common-testing'] +
     intDomainMods + intImplMods +
-    serviceModules +
+    serviceModules + svcDomainMods +
     presDomainMods + presImplMods
 ).sort()
 
 // app depends on all non-test, non-self modules
 def appDeps = allModules.findAll { it != 'acceptance-tests' && it != 'common-testing' && it != 'app' }
 
-// acceptance-tests depends on app + all domain modules
-def atDeps = (['app', 'common-domain'] + intDomainMods + presDomainMods).sort().unique()
+// acceptance-tests depends on app + all domain modules (including each service area's domain module)
+def atDeps = (['app', 'common-domain'] + intDomainMods + svcDomainMods + presDomainMods).sort().unique()
 
 // ─── Resolve Project Root ─────────────────────────────────────────────────────
 
@@ -386,7 +400,7 @@ try {
 writeFile(projectDir, 'common-domain/pom.xml',
     modulePom(groupId, artifactId, version,
         'common-domain',
-        'Domain classes common to all modules'))
+        'Domain classes common to all modules.'))
 srcTree(projectDir, 'common-domain', pkgPath,
     ['common/domain'], ['common/domain'],
     'Domain classes common to all modules.')
@@ -396,54 +410,67 @@ srcTree(projectDir, 'common-domain', pkgPath,
 writeFile(projectDir, 'common-testing/pom.xml',
     modulePom(groupId, artifactId, version,
         'common-testing',
-        'Testing utilities common to all test modules',
+        'Testing infrastructure common to all test modules.',
         ['common-domain']))
 srcTree(projectDir, 'common-testing', pkgPath,
-    ['common/testing'], [],
-    'Test utilities common to all modules.')
+    ['common/testing'], ['common/testing'],
+    'Test infrastructure common to all modules.')
 
 // ─── Integration: domain-{type}-{name} and integration-{type}-{name} ──────────
 
 integrations.each { intg ->
     def domMod  = "domain-${intg.abbrev}-${intg.name}"
     def implMod = "integration-${intg.abbrev}-${intg.name}"
+    def disp    = typeDisplay(intg.rawType)
+    def domSub  = "domain/${intg.abbrev}/${intg.name}"
+    def implSub = "integration/${intg.abbrev}/${intg.name}"
 
     writeFile(projectDir, "${domMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             domMod,
-            "Domain classes for ${intg.rawType} data source: ${intg.name}",
+            "Domain classes for the ${intg.name} ${disp} data source.",
             ['common-domain']))
     srcTree(projectDir, domMod, pkgPath,
-        ["domain/${intg.abbrev}/${intg.name}"],
-        ["domain/${intg.abbrev}/${intg.name}"],
-        "Domain classes for the ${intg.name} ${intg.rawType} integration.")
+        [domSub], [domSub],
+        "Domain classes for the ${intg.name} ${disp} integration.")
 
     writeFile(projectDir, "${implMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             implMod,
-            "Integration classes (DAOs, repositories) for ${intg.rawType}: ${intg.name}",
+            "Integration classes (DAOs, repositories) for the ${intg.name} ${disp} data source.",
             ['common-domain', domMod],
             failsafeSection))
     srcTree(projectDir, implMod, pkgPath,
-        ["integration/${intg.abbrev}/${intg.name}"],
-        ["integration/${intg.abbrev}/${intg.name}"],
-        "Integration classes for the ${intg.name} ${intg.rawType} data source.")
+        [implSub], [implSub],
+        "Integration classes for the ${intg.name} ${disp} data source.")
 }
 
 // ─── Service modules ──────────────────────────────────────────────────────────
 
 serviceModules.each { svcMod ->
     def label  = svcMod == 'service' ? 'primary' : svcMod.replaceFirst('service-', '')
     def svcPkg = svcMod == 'service' ? 'service'
-                                      : "service/${svcMod.replaceFirst('service-', '')}"
+                                      : "service/${label}"
+    def domMod = "domain-${svcMod}"
+    def domPkg = "domain/${svcPkg}"
 
-    writeFile(projectDir, "${svcMod}/pom.xml",
-        modulePom(groupId, artifactId, version,
-            svcMod,
-            "Business logic for the ${label} service area",
-            ['common-domain']))
     def svcDesc = svcMod == 'service' ? 'Business logic for the application.'
                                       : "Business logic for the ${label} service area."
+    def domDesc = svcMod == 'service' ? 'Domain classes for the application.'
+                                      : "Domain classes for the ${label} service area."
+
+    // Domain classes owned by this service area.
+    writeFile(projectDir, "${domMod}/pom.xml",
+        modulePom(groupId, artifactId, version,
+            domMod, domDesc,
+            ['common-domain']))
+    srcTree(projectDir, domMod, pkgPath, [domPkg], [domPkg], domDesc)
+
+    // Business logic, depending on its own service-area domain module.
+    writeFile(projectDir, "${svcMod}/pom.xml",
+        modulePom(groupId, artifactId, version,
+            svcMod, svcDesc,
+            ['common-domain', domMod]))
     srcTree(projectDir, svcMod, pkgPath, [svcPkg], [svcPkg], svcDesc)
 }
 
@@ -452,32 +479,33 @@ serviceModules.each { svcMod ->
 presentations.each { pType ->
     def domMod  = "domain-${pType}"
     def implMod = "presentation-${pType}"
+    def disp    = typeDisplay(pType)
 
     writeFile(projectDir, "${domMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             domMod,
-            "Domain classes for ${pType} presentation tier",
+            "Domain classes for the ${disp} presentation tier.",
             ['common-domain']))
     srcTree(projectDir, domMod, pkgPath,
         ["domain/${pType}"], ["domain/${pType}"],
-        "Domain classes for the ${pType} presentation tier.")
+        "Domain classes for the ${disp} presentation tier.")
 
     writeFile(projectDir, "${implMod}/pom.xml",
         modulePom(groupId, artifactId, version,
             implMod,
-            "Request handling classes (controllers) for ${pType}",
+            "Request-handling classes (controllers) for the ${disp} presentation tier.",
             ['common-domain', domMod]))
     srcTree(projectDir, implMod, pkgPath,
         ["presentation/${pType}"], ["presentation/${pType}"],
-        "Request-handling classes for the ${pType} presentation tier.")
+        "Request-handling classes for the ${disp} presentation tier.")
 }
 
 // ─── app ─────────────────────────────────────────────────────────────────────
 
 writeFile(projectDir, 'app/pom.xml',
     modulePom(groupId, artifactId, version,
         'app',
-        'Application assembly — produces the runnable artifact',
+        'Application assembly — produces the runnable artifact.',
         appDeps))
 srcTree(projectDir, 'app', pkgPath, ['app'], ['app'],
     'Application assembly and entry point.')
@@ -487,8 +515,8 @@ srcTree(projectDir, 'app', pkgPath, ['app'], ['app'],
 writeFile(projectDir, 'acceptance-tests/pom.xml',
     modulePom(groupId, artifactId, version,
         'acceptance-tests',
-        'Functional acceptance tests for the application',
+        'Functional acceptance tests for the application.',
         atDeps,
         failsafeSection))
-srcTree(projectDir, 'acceptance-tests', pkgPath, [], ['at'],
+srcTree(projectDir, 'acceptance-tests', pkgPath, ['at'], ['at'],
     'Functional acceptance tests for the application.')

src/site/asciidoc/modules.adoc

@@ -5,7 +5,8 @@
 
 Every module contains a full `src/` scaffold
 (`src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`)
-and a `package-info.java` in every applicable leaf package directory.
+with a `package-info.java` in each module's primary leaf package under both
+`src/main/java` and `src/test/java`.
 
 == Fixed Modules
 
@@ -17,7 +18,7 @@ Domain classes shared across all other modules. No dependencies on other generat
 _Package_: `{base.package}.common.domain`
 
 `common-testing`::
-Shared test utilities. Has no test-scope Java packages.
+Shared test infrastructure.
 +
 _Package_: `{base.package}.common.testing` +
 _Depends on_: `common-domain`
@@ -26,21 +27,27 @@ _Depends on_: `common-domain`
 Business logic for a service area (see the `serviceAreas` prompt).
 +
 _Package_: `{base.package}.service` or `{base.package}.service.{name}` +
+_Depends on_: `common-domain`, its own `domain-service` / `domain-service-{name}` module
+
+`domain-service` _or_ `domain-service-{name}`::
+Domain classes owned by a service area — one per `service` / `service-{name}` module.
++
+_Package_: `{base.package}.domain.service` or `{base.package}.domain.service.{name}` +
 _Depends on_: `common-domain`
 
 `app`::
 Application assembly — produces the runnable artifact (e.g. Spring Boot über-jar).
 +
 _Package_: `{base.package}.app` +
 _Depends on_: all non-test modules (`common-domain`, all domain and integration modules,
-all service modules, all presentation modules)
+all service modules and their `domain-service` modules, all presentation modules)
 
 `acceptance-tests`::
 Functional acceptance tests that exercise the application from the outside.
-Has no main-scope Java packages.
 +
 _Package_: `{base.package}.at` +
 _Depends on_: `app`, `common-domain`, all `domain-{type}-{name}` integration domain modules,
+all `domain-service` / `domain-service-{name}` service-area domain modules,
 all `domain-{type}` presentation domain modules +
 _Plugin_: `maven-failsafe-plugin` (`integration-test` + `verify` goals)
 
@@ -148,6 +155,8 @@ All type and name segments in package names are lowercased.
 |`integration-{type}-{name}` |`{base.package}.integration.{type}.{name}`
 |`service`                   |`{base.package}.service`
 |`service-{name}`            |`{base.package}.service.{name}`
+|`domain-service`            |`{base.package}.domain.service`
+|`domain-service-{name}`     |`{base.package}.domain.service.{name}`
 |`domain-{type}`             |`{base.package}.domain.{type}`
 |`presentation-{type}`       |`{base.package}.presentation.{type}`
 |`app`                       |`{base.package}.app`

src/site/asciidoc/requirements.adoc

@@ -80,10 +80,9 @@ Shared domain classes. No dependencies on other generated modules.
 
 === `common-testing`
 
-Shared test utilities.
+Shared test infrastructure.
 
 * Dependency: `common-domain`
-* No test-scope Java packages (the `src/test/java` directory is created but contains no source files).
 
 === Per integration: `domain-{type}-{name}` and `integration-{type}-{name}`
 
@@ -100,7 +99,12 @@ For each `type:name` integration entry, generate two modules
 === Per service area: `service` or `service-{name}`
 
 Business logic for a service area.
-Dependency: `common-domain`.
+Dependencies: `common-domain` and the area's own `domain-service` /
+`domain-service-{name}` module.
+
+For each service area, also generate a `domain-service` (single service) or
+`domain-service-{name}` module holding that area's domain classes
+(dependency: `common-domain`).
 
 === Per presentation tier: `domain-{type}` and `presentation-{type}`
 
@@ -121,19 +125,20 @@ and `app` itself.
 === `acceptance-tests`
 
 Functional tests that exercise the application end-to-end.
-No main-scope Java packages (the `src/main/java` directory is created but contains no source files).
 
 * Dependencies: `app`, `common-domain`, all `domain-{type}-{name}` modules,
+  all `domain-service` / `domain-service-{name}` modules,
   all `domain-{type}` (presentation) modules.
-* Do not depend on service modules or integration implementation modules.
+* Do not depend on service (business-logic) modules or integration implementation modules.
 * Configure `maven-failsafe-plugin` with the `integration-test` and `verify` goals.
 
 [[source-structure]]
 == Source Structure
 
 Each module's source root is the package derived from the base package prompt.
-Place a `package-info.java` in each leaf package directory with a Javadoc comment
-describing the package's purpose.
+Place a `package-info.java` in each module's primary leaf package under both
+`src/main/java` and `src/test/java`, with a Javadoc comment describing the package's
+purpose; the test-side comment is prefixed with "Tests for ...".
 The package for each module is:
 
 [cols="1,1"]
@@ -146,6 +151,8 @@ The package for each module is:
 |`integration-{type}-{name}` |`${base.package}.integration.{type}.{name}`
 |`service`                   |`${base.package}.service`
 |`service-{name}`            |`${base.package}.service.{name}`
+|`domain-service`            |`${base.package}.domain.service`
+|`domain-service-{name}`     |`${base.package}.domain.service.{name}`
 |`domain-{type}`             |`${base.package}.domain.{type}`
 |`presentation-{type}`       |`${base.package}.presentation.{type}`
 |`app`                       |`${base.package}.app`

src/site/asciidoc/usage.adoc

@@ -105,7 +105,8 @@ Produces: `acceptance-tests`, `app`, `common-domain`, `common-testing`, `service
 |===
 
 Produces: `acceptance-tests`, `app`, `common-domain`, `common-testing`,
-`domain-db-users`, `domain-rest`, `integration-db-users`, `presentation-rest`, `service`.
+`domain-db-users`, `domain-rest`, `domain-service`,
+`integration-db-users`, `presentation-rest`, `service`.
 
 === Full multi-service project
 
@@ -121,6 +122,7 @@ Produces: `acceptance-tests`, `app`, `common-domain`, `common-testing`,
 Produces: `acceptance-tests`, `app`, `common-domain`, `common-testing`,
 `domain-db-users`, `domain-graphql`, `domain-graphql-catalog`,
 `domain-rest`, `domain-rest-orders`,
+`domain-service-inventory`, `domain-service-orders`,
 `integration-db-users`, `integration-graphql-catalog`, `integration-rest-orders`,
 `presentation-graphql`, `presentation-rest`,
 `service-inventory`, `service-orders`.

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

@@ -28,6 +28,7 @@ assert !new File(basedir, 'pom.xml').exists() : "Root pom.xml must not exist; pa
 
 def modules = [
     'acceptance-tests', 'app', 'common-domain', 'common-testing',
+    'domain-service',
     'domain-db-main', 'domain-rest', 'integration-db-main',
     'presentation-rest', 'service'
 ]
@@ -161,11 +162,11 @@ assert text("acceptance-tests/src/test/java/${p}/at/package-info.java").contains
     assert content.startsWith('/**') : "${path} must start with a Javadoc comment"
 }
 
-// common-testing has no test Java packages; acceptance-tests has no main Java packages
-assert !new File(basedir, "common-testing/src/test/java/${p}/common/testing/package-info.java").exists() \
-    : 'common-testing must not have test Java package-info.java'
-assert !new File(basedir, "acceptance-tests/src/main/java/${p}/at/package-info.java").exists() \
-    : 'acceptance-tests must not have main Java package-info.java'
+// common-testing and acceptance-tests now carry package-info in both source roots
+assert new File(basedir, "common-testing/src/test/java/${p}/common/testing/package-info.java").exists() \
+    : 'common-testing must have test Java package-info.java'
+assert new File(basedir, "acceptance-tests/src/main/java/${p}/at/package-info.java").exists() \
+    : 'acceptance-tests must have main Java package-info.java'
 
 // ── 8. Module dependency wiring ───────────────────────────────────────────────
 
@@ -239,5 +240,11 @@ def psScript = text('parent/mvn-update-properties-versions.ps1')
 assert psScript.contains('mvn versions:update-properties')      : 'PowerShell script must run mvn versions:update-properties'
 assert psScript.contains('\r\n')                               : 'PowerShell script must use CRLF line endings'
 
+// ── #8 service-area domain module ────────────────────────────────────────────
+
+check('domain-service/pom.xml')
+assert text('domain-service/pom.xml').contains('<artifactId>common-domain</artifactId>') : 'domain-service missing common-domain dep'
+assert text('service/pom.xml').contains('<artifactId>domain-service</artifactId>')       : 'service must depend on domain-service'
+
 _buildLog.append("\n=== PASSED ===\n")
 true

src/test/resources/projects/blank-presentation-types/verify.groovy

@@ -30,6 +30,7 @@ assert !new File(basedir, 'pom.xml').exists() : "Root pom.xml must not exist"
 
 def modules = [
     'acceptance-tests', 'app', 'common-domain', 'common-testing',
+    'domain-service',
     'domain-db-main', 'integration-db-main', 'service',
 ]
 modules.each { m -> check("${m}/pom.xml") }
@@ -93,8 +94,8 @@ assert text("common-testing/src/main/java/${p}/common/testing/package-info.java"
 assert text("service/src/main/java/${p}/service/package-info.java").contains("package ${pkg}.service;")                      : 'service package-info.java has wrong package declaration'
 assert text("app/src/main/java/${p}/app/package-info.java").contains("package ${pkg}.app;")                                  : 'app package-info.java has wrong package declaration'
 assert text("acceptance-tests/src/test/java/${p}/at/package-info.java").contains("package ${pkg}.at;")       : 'acceptance-tests package-info.java has wrong package declaration'
-assert !new File(basedir, "common-testing/src/test/java/${p}/common/testing/package-info.java").exists()                     : 'common-testing must not have test Java package-info.java'
-assert !new File(basedir, "acceptance-tests/src/main/java/${p}/at/package-info.java").exists()                       : 'acceptance-tests must not have main Java package-info.java'
+assert new File(basedir, "common-testing/src/test/java/${p}/common/testing/package-info.java").exists()                     : 'common-testing must have test Java package-info.java'
+assert new File(basedir, "acceptance-tests/src/main/java/${p}/at/package-info.java").exists()                       : 'acceptance-tests must have main Java package-info.java'
 
 // ── 7. Dependency wiring ─────────────────────────────────────────────────────