docs(site): Add initial Maven site docs

Author: jeffjensen

src/site/asciidoc/developing.adoc

@@ -0,0 +1,107 @@
+= Developing
+:toc: left
+:toc-title: Contents
+:toclevels: 2
+
+== Prerequisites
+
+* Java 21 or later
+* Maven 3.6 or later (or use the included wrapper: `./mvnw` / `mvnw.cmd`)
+
+== Build and Install
+
+The project includes a Maven wrapper — no local Maven installation required.
+
+[source,bash]
+----
+./mvnw install
+----
+
+This installs the archetype into your local Maven repository so it can be used immediately.
+
+On Windows use `mvnw.cmd install`.
+
+== Running the Full Build
+
+Run the full build including all integration tests:
+
+[source,bash]
+----
+./mvnw verify
+----
+
+== Integration Tests
+
+Each integration test generates a complete project from the archetype using a fixed set of inputs,
+then runs Groovy assertions against the result.
+All test cases live under `src/test/resources/projects/`.
+
+=== Test structure
+
+Each test is a directory containing three files:
+
+`archetype.properties`::
+Property values passed to the archetype at generation time — the Maven coordinates plus the
+four archetype-specific properties (`integrations`, `singleService`, `serviceAreas`, `presentationTypes`).
+
+`goal.txt`::
+The Maven goal to run against the generated project after generation.
+All tests use `-f parent/pom.xml verify`.
+
+`verify.groovy`::
+Groovy assertions that run after generation.
+The script receives `basedir` pointing at the generated project root and asserts on
+file existence, POM content, source structure, and dependency wiring.
+
+=== Test output
+
+Generated projects are written to:
+
+[source]
+----
+target/test-classes/projects/{test-name}/project/{artifactId}/
+----
+
+These files persist until the next `mvn clean` and can be inspected directly to see exactly
+what the archetype produces for a given set of inputs.
+
+Each test also writes a `build.log` in the generated project root.
+The `verify.groovy` script prepends the test name and the `archetype.properties` content
+to the log before appending any output, so a single file captures both the inputs and the
+build result for that test run.
+
+=== Adding a new integration test
+
+. Create a directory under `src/test/resources/projects/{test-name}/`.
+. Add `archetype.properties` with the inputs to test.
+. Add `goal.txt` containing `-f parent/pom.xml verify`.
+. Add `verify.groovy` with assertions against the generated output.
+. Run `./mvnw verify` — the new test is picked up automatically.
+
+== Project Structure
+
+[source]
+----
+src/
+├── main/resources/
+│   ├── META-INF/
+│   │   ├── archetype-post-generate.groovy  (all module generation logic)
+│   │   └── maven/
+│   │       └── archetype-metadata.xml      (property declarations and defaults)
+│   └── archetype-resources/
+│       └── pom.xml                         (placeholder; deleted by post-generate script)
+├── site/
+│   ├── site.xml                            (navigation)
+│   └── asciidoc/                           (site pages)
+└── test/resources/projects/
+    └── {test-name}/
+        ├── archetype.properties
+        ├── goal.txt
+        └── verify.groovy
+----
+
+All module generation logic lives in `archetype-post-generate.groovy`.
+It reads the archetype properties, computes the full module list, and writes every
+`pom.xml`, source directory, and `package-info.java` from scratch.
+The placeholder `archetype-resources/pom.xml` satisfies the Maven Archetype Plugin's
+packaging requirements and is deleted immediately by the script.

src/site/asciidoc/index.adoc

@@ -0,0 +1,50 @@
+= Java Service Archetype
+:toc: left
+:toc-title: Contents
+:toclevels: 2
+
+Maven archetype that generates a structured multi-module Java service project.
+Describe your integrations, service areas, and presentation architectural tiers at generation time;
+the archetype builds the full module tree and wires up all POMs.
+
+== Quick Start
+
+[source,bash]
+----
+./mvnw archetype:generate \
+  -DarchetypeGroupId=io.github.jeffjensen \
+  -DarchetypeArtifactId=java-service-archetype \
+  -DarchetypeVersion=1.0.0-SNAPSHOT
+----
+
+Maven prompts for standard coordinates (`groupId`, `artifactId`, `version`, `package`)
+followed by four archetype-specific properties.
+See link:usage.html[Usage] for the full prompts reference.
+
+== Example Output
+
+Given `integrations=database:users,rest:orders`, `singleService=y`, `presentationTypes=rest`,
+the archetype produces:
+
+[source]
+----
+my-service/
+├── parent/                     (aggregator POM — build entry point)
+│   └── pom.xml
+├── acceptance-tests/
+├── app/
+├── common-domain/
+├── common-testing/
+├── domain-db-users/
+├── domain-rest/
+├── domain-rest-orders/
+├── integration-db-users/
+├── integration-rest-orders/
+├── presentation-rest/
+└── service/
+----
+
+`parent/` is a sibling directory — there is no `pom.xml` at the project root.
+Each module contains a full `src/` scaffold and a `package-info.java` in every leaf package.
+
+See link:modules.html[Modules] for a description of each module, its dependencies, and how to build.

src/site/asciidoc/modules.adoc

@@ -0,0 +1,123 @@
+= Generated Modules
+:toc: left
+:toc-title: Contents
+:toclevels: 2
+
+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.
+
+== Fixed Modules
+
+These modules are always generated regardless of input.
+
+`common-domain`::
+Domain classes shared across all other modules. No dependencies on other generated modules.
++
+_Package_: `{base.package}.common.domain`
+
+`common-testing`::
+Shared test utilities. Has no test-scope Java packages.
++
+_Package_: `{base.package}.common.testing` +
+_Depends on_: `common-domain`
+
+`service` _or_ `service-{name}`::
+Business logic for a service area (see `singleService` and `serviceAreas` prompts).
++
+_Package_: `{base.package}.service` or `{base.package}.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)
+
+`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-{type}` presentation domain modules +
+_Plugin_: `maven-failsafe-plugin` (`integration-test` + `verify` goals)
+
+== Integration Modules
+
+Generated per `type:name` pair in the `integrations` prompt.
+The `database` type is abbreviated to `db` in all names.
+
+`domain-{type}-{name}`::
+Domain classes for a specific integration (e.g. `domain-db-users`, `domain-rest-orders`).
++
+_Package_: `{base.package}.domain.{type}.{name}` +
+_Depends on_: `common-domain`
+
+`integration-{type}-{name}`::
+Integration implementation classes — DAOs, Spring Data JPA repositories, REST clients, etc.
+(e.g. `integration-db-users`, `integration-rest-orders`).
++
+_Package_: `{base.package}.integration.{type}.{name}` +
+_Depends on_: `common-domain`, `domain-{type}-{name}` +
+_Plugin_: `maven-failsafe-plugin` (`integration-test` + `verify` goals)
+
+== Presentation Modules
+
+Generated per type in the `presentationTypes` prompt.
+
+`domain-{type}`::
+Domain classes for a presentation tier (e.g. `domain-rest`, `domain-graphql`).
++
+_Package_: `{base.package}.domain.{type}` +
+_Depends on_: `common-domain`
+
+`presentation-{type}`::
+Request-handling classes — controllers, resolvers, etc.
+(e.g. `presentation-rest`, `presentation-graphql`).
++
+_Package_: `{base.package}.presentation.{type}` +
+_Depends on_: `common-domain`, `domain-{type}`
+
+== Parent POM
+
+`parent/pom.xml` is the aggregator and BOM for all sibling modules.
+There is no `pom.xml` at the project root — `parent/` is a sibling of all other modules.
+
+It contains:
+
+* `<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`
+* Common properties: Java 21 via `maven.compiler.release`; UTF-8 source encoding
+* `<pluginManagement>` — pinned versions for `maven-compiler-plugin`, `maven-failsafe-plugin`,
+  `maven-jar-plugin` (with `skipIfEmpty=true`), and `maven-surefire-plugin`
+
+To build a generated project:
+
+[source,bash]
+----
+cd my-service/parent
+mvn install
+----
+
+== Package Reference
+
+All type and name segments in package names are lowercased.
+
+[cols="1,1"]
+|===
+|Module |Package
+
+|`common-domain`             |`{base.package}.common.domain`
+|`common-testing`            |`{base.package}.common.testing`
+|`domain-{type}-{name}`      |`{base.package}.domain.{type}.{name}`
+|`integration-{type}-{name}` |`{base.package}.integration.{type}.{name}`
+|`service`                   |`{base.package}.service`
+|`service-{name}`            |`{base.package}.service.{name}`
+|`domain-{type}`             |`{base.package}.domain.{type}`
+|`presentation-{type}`       |`{base.package}.presentation.{type}`
+|`app`                       |`{base.package}.app`
+|`acceptance-tests`          |`{base.package}.at`
+|===