Spring Boot example (minimal CRUD service)

This page describes the release 1.3.80 SpringBoot generation example. It combines a manually maintained application shell with generated artefacts for:

• API layer (DTOs, API interface, controller)
• domain layer (domain types)
• persistence (JPA entities, repositories)
• data access service (decoupled persistence adapter)
• mapping (via MapStruct)

It shows the generated baseline before adding project-specific services while keeping generated and manual ownership separate.

Release baseline

Canonical source: example-spring-boot from release/1.3.80, commit df7cabf7f21b. The verification scope and date are recorded in section 3.

1. Repository and download

The complete example is the example-spring-boot module on release/1.3.80.

It contains:

• CMN models defining domain types, the API and the component/application binding
• a manually maintained Spring Boot application shell
• generated Spring Boot artefacts

2. Project structure

After generation you will find the following source trees:

Source path	Purpose
src/generated/java/org/joinedworkz/examples/customer/entity	JPA entities (storage model)
src/generated/java/org/joinedworkz/examples/customer/repository	Spring Data repositories
src/generated/java/org/joinedworkz/examples/customer/das	DataAccessService layer
src/generated/java/org/joinedworkz/examples/customer/dto	API request/response DTOs
src/generated/java/org/joinedworkz/examples/customer/mapper	MapStruct mapper interfaces
src/generated/java/org/joinedworkz/examples/customer/webapp/customers/v1/api	API interface
src/generated/java/org/joinedworkz/examples/customer/webapp/customers/v1/controller	REST controller

This layout follows the conventions from:

→ SpringBoot target platform design

3. Verified scope

Requirements:

• Java 21
• Maven 3.9 or newer

Generation, main-source compilation and packaging were verified offline with the published JoinedWorkz 1.3.80 artifacts, Java 21.0.8 and Maven 3.9.16 on 2026-07-26:

mvn clean verify

The generator also writes src/generated/test/org/joinedworkz/examples/customer/webapp/customers/v1/it/CustomersResourceIT.java. The module does not register src/generated/test as a Maven test source: testCompile had no sources and no tests ran. An end-to-end runtime/CRUD smoke test has not yet been completed. Start commands, ports and concrete HTTP requests are therefore deliberately not presented as verified behaviour.

Generated ownership is explicit: src/generated/** is replaceable. The application shell src/main/java/org/joinedworkz/examples/SpringBootExampleApplication.java and src/main/resources/application.properties are maintained manually.

4. Request flow

A typical request flows through:

1. CustomerV1Controller receives a DTO, identifier or query parameters.
2. The controller calls CustomerDataAccessService directly.
3. The data access service uses CustomerMapper to map between CustomerDto and the JPA entity Customer.
4. The data access service reads or writes through CustomerRepository.
5. Results are mapped back to CustomerDto.
6. The controller returns the HTTP response.

5. Canonical release model excerpt

core package org.joinedworkz.examples.customer

import org.joinedworkz.facilities.common.base
import org.joinedworkz.facilities.profiles.springboot

platform SpringBoot

type<entity> Customer {
    id**:       Id
    firstName*: Name
    lastName*:  Name
    email:      String(255)
}

The API model uses the SpringBoot CRUD method types:

api package org.joinedworkz.examples.customer.api

import org.joinedworkz.examples.customer
import org.joinedworkz.facilities.profiles.springboot
import org.joinedworkz.facilities.springboot.api

platform SpringBoot

resource /customers as Customer[] by id {
    queryEntities()
    createEntity()
    readEntity()
    updateEntity()
    deleteEntity()
}

The third model makes the component provide that resource. This boundary drives controller/API-interface generation and the additional component-scoped OpenAPI aggregate:

package org.joinedworkz.examples.backend

import org.joinedworkz.examples.customer.api
import org.joinedworkz.facilities.profiles.springboot

platform SpringBoot

component CustomerBackend
    basePackage='org.joinedworkz.examples.customer.webapp' {

    provide /customers
        subPackage='customers.v1'
        controller="CustomerV1Controller" {
    }
}

application CustomerApp {
    consists of {
        CustomerBackend
    }
}

Release 1.3.80 therefore emits both the model-scoped src/generated/resources/openapi/org.joinedworkz.examples.customer.api.yaml and the component-scoped src/generated/resources/openapi/org.joinedworkz.examples.backend_customerbackend.yaml. The matching viewers are diagram/api/org.joinedworkz.examples.customer.api.html and diagram/api/org.joinedworkz.examples.backend_customerbackend.html. The component document combines all endpoints provided by CustomerBackend; the application does not create another OpenAPI aggregate.

6. Extending the example

Typical next steps:

• add project-specific application or domain services
• introduce additional API views
• route generated Java classes to separate Maven modules by layer/source tag
• add gateways for external systems

For deeper information:

• SpringBoot target platform design
• SpringBoot profile & canonical modeling
• Spring Boot facility