Profiles and platforms

Most application developers use profiles delivered by a Facility; they do not write .profile files themselves. This page explains the consumer-facing workflow.

If you want to implement your own Facility, continue with Build a custom Facility instead.

1. Facility, Profile and Platform

These terms describe different parts of the same generation setup:

• A Facility is a Maven artifact that packages reusable modeling definitions and generation behavior.
• A Profile is a .profile resource inside a Facility. It declares named Platforms and their Cartridges, Outlets and configuration contract.
• A Platform is the named generation configuration selected by a CMN model, for example Base, Java or SpringBoot.
• A Cartridge invokes generators for one concern, such as OpenAPI, Java DTOs or Spring Boot persistence.
• An Outlet is a named destination through which a Cartridge writes files.

A Facility can provide one or more Platforms. A Platform is therefore not a Maven artifact of its own, and adding a Facility dependency does not automatically select its Platform for every model.

2. Choose a Facility

The public documentation covers the stable Base, Java and SpringBoot Facilities and the experimental Quasar Facility. Their Maven coordinates, Platform names, lifecycle and generated outputs are listed in Facilities and platforms.

That list covers the Facilities delivered and documented by JoinedWorkz. It is not a closed registry: organizations can provide additional Facilities and Platforms.

3. Make the Platform available

Add the Facility used by the model to that model module's Maven dependencies. For example, a SpringBoot model uses:

<dependency>
    <groupId>org.joinedworkz.facilities</groupId>
    <artifactId>spring-boot</artifactId>
    <version>${joinedworkz.version}</version>
    <scope>provided</scope>
</dependency>

The dependency belongs on the model module's compile classpath. provided keeps the build-time Facility available to the JoinedWorkz Maven plugin without turning it into an application runtime dependency.

The complete plugin and classpath contract is documented in the Maven plugin reference.

4. Select the Platform in CMN

The Facility dependency, imports and Platform selection have separate jobs:

package com.example.customer

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

platform SpringBoot

type Customer {
    name*: String
}

1. The Maven dependency makes the Facility's profiles, shared CMN models and implementation classes available to the generator.
2. Imports make the referenced profile and CMN namespaces visible to this model.
3. platform SpringBoot selects the generation behavior for this model.

Excluding a Cartridge

A model can exclude a Cartridge that its selected Platform would otherwise apply:

platform SpringBoot exclude DtoCartridge

Use only Cartridge names documented by the selected Facility. An exclusion is local to that CMN Platform selection; it does not remove the Facility dependency or change the Platform definition.

For the complete enablement precedence, see Cartridge enablement.

5. Understand Platform inheritance

The built-in public Platforms form this hierarchy:

Base
├── Java
│   └── SpringBoot
└── Quasar (experimental)

A specialized Platform inherits the active behavior of its parent. Selecting SpringBoot, for example, can produce Base OpenAPI and diagram output, Java DTOs and SpringBoot-specific output. Configure and review the complete output set documented by the selected Facility, not only its most specialized Cartridge.

An importing model's Platform can also contribute active Cartridge processing to an imported model without changing that model's namespace or existing Platform selection. This is an advanced mechanism; see Imported model processing and diagnostics.

6. Configure the project

Project-specific generation configuration belongs in joinedworkz.properties, not in a copied or modified Facility profile. Use it to configure documented options such as:

• global or layer-specific Outlet directories;
• Cartridge enablement;
• Facility-defined configuration properties; and
• generated Java package overrides.

The supported patterns, precedence and diagnostics are in the joinedworkz.properties reference. Facilities can define additional Outlets and properties, so use the contract of the Facility you actually depend on rather than guessing names.

7. Treat generated output according to its ownership

A Profile's Outlet flags control generator and filesystem behavior. They do not by themselves decide whether a file belongs in Git or whether Maven Clean removes a directory.

Before editing or deleting generated files, classify them as replaceable, first-cut/manual or stateful output using Generated output, ownership and regeneration.

8. Next steps

• Select a supported Facility from the Facility matrix.
• Configure the model build with the Maven plugin reference.
• Look up the Platform's concrete outputs and properties on its Facility page.
• For advanced cross-model composition, read Imported model processing and diagnostics.
• To create a reusable extension, enter the separate Extending JoinedWorkz path.