SpringBoot target platform design

This page describes the artifacts and call paths generated by the SpringBoot platform. It separates that generated contract from optional architecture conventions chosen by an application project.

The corresponding modeling rules are documented in:

• SpringBoot profile and canonical modeling
• ID generation strategies
• Repository statements and composition
• Spring Boot facility

Generated packages are not automatically manual extension points. Use the ownership and regeneration reference to distinguish replaceable output, first-cut files and manually maintained application sources.

1. Generated persistence artifacts

For a CMN type<entity> Customer, SpringBoot generates a related group of artifacts:

• CustomerDto is the detached Java representation generated from the CMN type.
• Customer is the Jakarta Persistence entity with table, column and relationship mappings.
• CustomerMapper is a MapStruct mapper between the DTO and entity. It also updates an existing entity from a DTO.
• CustomerRepository is a Spring Data repository for the entity and its key type. Advanced entity operations can add explicit JPQL or native SQL @Query methods to this repository.
• CustomerDataAccessService combines repository access, query execution and entity/DTO mapping. It exposes the generated persistence operations used by the opinionated CRUD resource methods.

The default persistence call path is:

DTO -> DataAccessService -> Mapper -> Entity -> Repository -> database

The response follows the reverse mapping from entity to DTO. The generated controller path therefore does not return JPA entities as its normal public representation.

For an entity key without generation, this path expects an assigned value. For CUSTOM, the generated data-access service contributes a UUID expression and the reference AbstractDataAccessService.create(dto) lifecycle invokes it only when the incoming DTO has no ID. Calling the generated save(...) method or a Spring Data repository directly bypasses that application-side hook. UUID, AUTO, IDENTITY, SEQUENCE and TABLE instead emit JPA provider annotations and run at the persistence boundary. The complete contract is in ID generation strategies.

An explicit statement operation stays on the persistence path. Its generated repository method and data-access method are available to manual application code or a generated handler, but the entity operation alone does not create a resource or controller operation. Native complex results pass through the generated tuple-to-DTO mapping described in Repository statements and composition.

2. Generated HTTP artifacts

A CMN resource defines paths, operations, representations and identifiers. A component must provide the resource before SpringBoot generates its HTTP adapter:

• an API interface containing Spring Web and OpenAPI annotations;
• a REST controller implementing that interface.

The component's componentNamespace and the provided boundary's optional namespaceSuffix form the target namespace for both artifacts. SpringBoot adds .api for the interface and .controller for the implementation. When componentNamespace is absent, the component model's CMN namespace is the default. These target namespaces do not change the modeled HTTP path.

Several provided boundaries can partition a nested resource tree. An operation belongs to the deepest matching boundary, so a nested subtree can have a different API interface and controller from its parent while both remain part of the same component.

For an opinionated CRUD method that uses an entity representation, the controller delegates directly to the generated data access service:

HTTP request
  -> API interface / REST controller
  -> DataAccessService
  -> Repository and Mapper
  -> DTO response

For query operations, the controller also turns paging, filtering and sorting parameters into the query specification consumed by the data access service. Modeled request-header names become optional String parameters in the API, controller and handler call. A separately enabled complete-header map is a SpringBoot runtime contract and is not expanded into arbitrary static OpenAPI parameters. See Request headers and handler signatures.

The resource may use the domain DTO directly. A separate API view is optional. When a distinct API view is modeled with source-field relationships, SpringBoot generates an additional MapStruct mapping between the API view and its source DTO:

HTTP API view
  -> API-view mapper
  -> source DTO
  -> DataAccessService
  -> entity persistence

This mapping is generated only when JoinedWorkz can determine the source type. A partially related API view is not a supported runtime shortcut.

3. Optional handler path

A resource operation can name a custom handler instead of delegating directly to a data access service. The resulting call path is:

HTTP request -> REST controller -> handler -> application-specific behavior

Handler selection is operation-specific. One generated controller can inject several handlers and delegate different operations to them. A handlerClass on a nested resource applies to its subtree and overrides a class selected on an ancestor resource; an operation-level class or combined handler setting can select another target. The detailed precedence and default naming rules are documented under Controller and handler composition.

When JoinedWorkz creates such a handler, its interface is replaceable generated output. Its initial implementation is first-cut source and contains an unimplemented method until the application developer completes it. Subsequent generation does not replace that manual implementation.

The handler is an optional extension path, not a mandatory layer between every controller and data access service. Any additional handwritten services used by a handler belong to the project architecture rather than to the generated SpringBoot contract.

When a custom handler consumes request headers, its generated signature follows the same parameter order as the controller invocation. The selected-header and complete-map contracts, including the security boundary for the map, are documented under Request headers and handler signatures.

4. Default package roles

The standard generated package suffixes describe artifact roles:

• dto — detached Java representations;
• entity — Jakarta Persistence entities;
• mapper — MapStruct mappers;
• repository — Spring Data repositories;
• das — data access services;
• api — controller-level Java interfaces;
• controller — REST controller implementations.

For a provided boundary, the HTTP-related defaults are:

<componentNamespace>[.<namespaceSuffix>].api
<componentNamespace>[.<namespaceSuffix>].controller
<componentNamespace>[.<namespaceSuffix>].handler

The .handler package is used for unqualified or derived custom-handler classes. A fully qualified handlerClass remains independent of this default. The deprecated compatibility names basePackage and subPackage retain the same component/provide semantics but should not be used in new models.

These packages do not prescribe Maven module boundaries. Package overrides can substitute configured package prefixes in generated Java references, while outlet routing determines the physical source directory.

5. CMN layers versus architecture layers

A CMN layer normally becomes the effective layer for generated output. It can route files to a source directory, but it does not automatically create a domain, application or infrastructure layer. A specialized generator can assign a different effective layer to a particular output.

Projects often use:

• core for domain-oriented models;
• backend for component or application models.

These are project conventions. SpringBoot does not assign additional generator behavior to either name.

Two names have additional SpringBoot behavior:

• api selects API-oriented DTO/mapper routing, and generated controllers and API interfaces are explicitly assigned effective layer api;
• mapping selects generatedMappingSource for DTOs and entity mappers.

SpringBoot also inherits the Java facility's external convention. This layer implicitly selects plain DTO naming unless the package or one of its parents declares skipDtoPostfix; it is not a SpringBoot-specific routing rule.

The complete routing and DTO-naming precedence are described in SpringBoot profile and canonical modeling.

6. Single-module and multi-module applications

The generated artifact flow works in either layout.

In a single module, the default outlets place the generated Java artifact families under the same generated source root. This keeps the initial build configuration compact.

In a multi-module application, layer-specific outlet properties can route selected output to separate domain, mapping or web modules. The chosen layer names describe the project's organization; only the documented api and mapping names add SpringBoot-specific behavior. The inherited Java external convention affects DTO naming as described above.

Module boundaries must still follow Java dependencies. For example, a web module containing the generated controller needs the API/DTO types and the handler or data access service it invokes. A persistence module needs its entities, repositories, mappers and Spring persistence dependencies.

7. Ownership and runtime boundary

The generated DTO, entity, mapper, repository, data access service, API interface and controller are replaceable output. Application behavior that must survive regeneration belongs in manual code or a documented first-cut extension.

The application shell and its runtime configuration are manually maintained. They provide component scanning, datasource configuration, database connectivity and the dependencies required by generated sources.

The generated data-access service is replaceable output, and its base-class import can be rewritten with a package override. A replacement AbstractDataAccessService owns the resulting create lifecycle, including whether and when the generated CUSTOM hook runs and whether an explicit ID wins. Compile and exercise both missing- and explicit-ID cases after replacing that glue contract.

Changing the SpringBoot flavor can change DTO member names and database identifiers across several generated artifacts. Apply the clean regeneration and migration workflow from the modeling page; never retain a mixture of different flavor outputs.

8. Summary

The generated SpringBoot contract is centered on two explicit paths:

resource + component -> API interface + controller
entity type -> DTO + entity + mapper + repository + DataAccessService

Opinionated CRUD controllers connect those paths directly. Custom handlers and additional application services are deliberate project extensions, while CMN layers and generator-assigned effective layers primarily control physical output routing.