Create a project with Maven Archetypes

The JoinedWorkz Maven Archetypes create independent, runnable multi-module projects without requiring a JoinedWorkz source checkout. Use them when you want to start a new Spring Boot application or a Spring Boot application with an experimental Quasar frontend.

If you first want to understand the model, Maven plugin and generated output in isolation, use the transparent Base Quickstart. To add JoinedWorkz to an existing project or design a custom module layout, use the manual Maven setup.

Release compatibility

Archetype release 1.3.0 targets JoinedWorkz 1.3.81, Java 21 and Maven 3.9+. Archetype versions and JoinedWorkz versions are independent; use the compatibility matrix instead of assuming that their version numbers match.

1. Choose an Archetype

Spring Boot

joinedworkz-spring-boot-archetype is the stable starter. It creates a model module, a mixed-ownership backend core module and a manual Spring Boot application shell.

Spring Boot with Quasar

joinedworkz-fullstack-quasar-archetype adds a Quasar frontend and its manual application shell around generated pages, routes and store. The shell includes the shared helpers, styles, filter editor, reusable widgets and focused tests needed by the generated frontend. The Spring Boot backend is stable; the Quasar frontend is experimental.

Both templates use a compact Category and Item domain. They demonstrate an ItemView with an optional entity reference, a genuinely paginated native SQL list query, a default-JPQL detail query, an application-owned custom handler and value converter, and a timestamp mapped to java.time.Instant and TIMESTAMP WITH TIME ZONE. The full-stack template also models list, detail and Create Pages plus selection-based removal actions for both entities.

Both Archetypes use the Maven group org.joinedworkz.archetypes. Their source, descriptors and starter templates are maintained in the joinedworkz-archetypes repository.

2. Prerequisites

Install:

• Java 21;
• system-installed Maven 3.9 or newer (mvn on PATH); and
• Docker or another reachable PostgreSQL installation only when you select postgresql.

Use system Maven for both project generation and subsequent builds. The H2 variant runs with a persistent project-local database and does not require Docker.

The full-stack Maven build installs its pinned Node.js and npm versions below the frontend module, so a global Node.js installation is not required for mvn clean verify. Interactive frontend development uses Node.js 22.22.2 and npm 11.6.0.

Do not build a generated reactor with Maven's parallel -T option. Model generation writes into downstream sibling modules, so the reactor order must remain sequential.

3. Generate a Spring Boot project

The following command creates a runnable application backed by H2:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.1:generate \
  -DarchetypeGroupId=org.joinedworkz.archetypes \
  -DarchetypeArtifactId=joinedworkz-spring-boot-archetype \
  -DarchetypeVersion=1.3.0 \
  -DgroupId=com.example \
  -DartifactId=catalog-service \
  -Dversion=1.0.0 \
  -Dpackage=com.example.catalog \
  -DapplicationName=CatalogService \
  -DapplicationTitle="Catalog Service" \
  -Ddatabase=h2

Build and start the generated project:

cd catalog-service
mvn clean verify
java -jar backend-spring-app/target/catalog-service-backend-spring-app-1.0.0.jar

The starter APIs are available below http://localhost:8080/api/v1/categories and http://localhost:8080/api/v1/items. Swagger UI is available at http://localhost:8080/swagger-ui.html.

The generated reactor contains:

model
backend-spring-core
backend-spring-app

4. Generate a Spring Boot and Quasar project

The full-stack Archetype adds an experimental model-generated Quasar frontend. This example embeds the production frontend build in the Spring Boot application:

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.1:generate \
  -DarchetypeGroupId=org.joinedworkz.archetypes \
  -DarchetypeArtifactId=joinedworkz-fullstack-quasar-archetype \
  -DarchetypeVersion=1.3.0 \
  -DgroupId=com.example \
  -DartifactId=catalog-application \
  -Dversion=1.0.0 \
  -Dpackage=com.example.catalog \
  -DapplicationName=CatalogApplication \
  -DapplicationTitle="Catalog Application" \
  -Ddatabase=h2 \
  -DfrontendDelivery=spring-boot

Build and start the backend:

cd catalog-application
mvn clean verify
java -jar backend-spring-app/target/catalog-application-backend-spring-app-1.0.0.jar

Create one item through the generated backend API:

curl -X POST http://127.0.0.1:8080/api/items \
  -H 'Content-Type: application/json' \
  -d '{"name":"First item","description":"Created through the generated API","createdAt":"2026-03-01T10:00:00Z"}'

Open http://127.0.0.1:8080/items for the embedded production frontend. The API is available below http://127.0.0.1:8080/api/items, and Swagger UI is at http://127.0.0.1:8080/swagger-ui.html.

The generated Item and Category list pages link to dedicated Create Pages. Their header actions can also remove the current table selection through the generated API and the application-owned bulk handlers. A Category cannot be deleted while Items reference it: first reassign, explicitly clear or remove those references. The foreign key does not cascade deletion, and the bulk handler does not define a dedicated HTTP conflict response.

For interactive frontend development, leave the backend running and start the Quasar development server in a second terminal:

cd frontend-quasar
npm ci
npm run dev

Then open http://127.0.0.1:9000/items. The development server proxies /api to the backend on port 8080.

The generated reactor contains:

model
backend-spring-core
frontend-quasar
backend-spring-app

5. Parameters

Provide the standard Maven coordinates and Java package explicitly for a reproducible non-interactive command:

Parameter	Contract
groupId	Maven group of the generated project
artifactId	Maven artifact and generated project-directory name
version	Initial version of the generated project
package	Base Java package for manual application source
applicationName	Application identifier; starts with an uppercase letter and then uses only letters or digits; default Application
applicationTitle	Human-readable title; quote values containing spaces; default JoinedWorkz Application
database	h2 or postgresql; default h2
frontendDelivery	Full-stack only: standalone or spring-boot; default standalone

With database=h2, runtime data is stored below the generated project's .data directory and tests use a separate in-memory database. With database=postgresql, use the included compose.yaml, a local PostgreSQL server or another reachable instance.

With frontendDelivery=spring-boot, the production SPA is packaged into the backend application. With frontendDelivery=standalone, Maven leaves the production files below frontend-quasar/dist/spa; deploy that directory with a static server that supports history-mode fallback and routes /api to the backend.

6. Ownership after generation

The Archetype creates authoritative CMN models and application-owned shells. The backend-spring-core module intentionally combines different ownership classes:

• src/generated receives replaceable Java and OpenAPI output;
• src/main/java contains persistent first-cut handlers and the application-owned value converter; and
• src/main/resources/db contains the reviewed V1 and V2 Flyway migrations and matching schema snapshots.

The full-stack template uses the same distinction between replaceable frontend-quasar/src/generated output and the application-owned Quasar shell outside that directory. Replaceable Java, OpenAPI and Quasar output is absent from the template and appears during the first build. Change the CMN source and regenerate instead of editing those generated files. Preserve the Flyway migrations and snapshots as persistent database history.

The generated project README identifies the exact manual, first-cut, replaceable and persistent paths for the selected variant. See Generated output and ownership before restructuring the generated modules.

The starters use genesis-spring as ready-to-run Glue Code for examples, prototypes and first experiments. Production projects can provide compatible project-owned implementations, route the generated imports with package overrides and remove the Genesis runtime dependency.

7. AI-assisted development

Both Archetypes include the complete Framework Core for JoinedWorkz 1.3.81, covering concepts, CMN, Profiles, all documented Facility topics and examples:

AGENTS.md
ai/
  project-context/
    README.md
    project-context.meta.json
    ... topic documents
  joinedworkz-context-core/
    README.md
    joinedworkz.meta.json
    framework/
    facilities/
    examples/

Start with the task and AGENTS.md, which points to the project entry. The project context describes the generated application and is parameterized for its name, Maven coordinates, Java package, database and, where applicable, frontend delivery. Follow Task → Project → Framework: read the required entry and development/usage rules once, then load the relevant topic documents on demand. The complete local pack is not a mandatory initial prompt.

The backend-only starter also includes Quasar knowledge. Its presence does not configure a frontend or activate an additional Facility. Keep project context consistent with the application's evolving model and configuration.

project-context.meta.json records the original Archetype coordinates and the Framework-context source repository, AI Context version 2.0.0 and path under initial_context_distribution. This identifies the initially supplied Context, not the current state of subsequently edited project documents.

The Framework Core comes from the JoinedWorkz AI Context repository and is available locally without a web lookup. The AI Context guide explains topic selection and use in existing projects.

8. Troubleshooting

• Use the explicit plugin and Archetype coordinates shown above. Do not add -DarchetypeCatalog=local; that option is for locally installed Archetypes, not the public release.
• Shortly after publication, Maven can report that an Archetype is not yet in a catalog and then fall back to Maven Central. This is informational when the download and generation continue.
• If Maven cached an earlier failed lookup, rerun the same command with -U before changing any coordinates.
• Parameter values are case-sensitive. Use h2 or postgresql and, for the full-stack Archetype, standalone or spring-boot.
• The first full-stack build downloads the pinned frontend toolchain and can therefore take longer than later builds.

See the symptom-first Troubleshooting reference for resolution and parameter diagnostics.