Core concepts: model, platforms, cartridges, generators

JoinedWorkz is built around a small set of core concepts:

• Model – what your system should do, described in Canonical Model Notation (CMN)
• Platform – the technical environment in which the model is realised
• Cartridge – a bundle of generators for a specific aspect of a platform
• Generator – code that turns a model into platform-specific artifacts

On top of that, JoinedWorkz provides tooling:

• JoinedWorkz Studio for rich editing
• the JoinedWorkz Maven plugin for command-line and CI/CD integration
• and a set of reusable base models, platforms and cartridges

Models and Canonical Model Notation (CMN)

A JoinedWorkz model is a text file with the extension .cmn (Canonical Model Notation). Models describe:

• packages – namespaces for your domain
• imports – references to other models
• platform selection – which platform(s) this model is intended for
• resources and operations – for example REST-like APIs
• types – entities, DTOs and other data structures

Example: a minimal API model

package com.example.joindeworkz.quickstart

import org.joinedworkz.facilities.common.base.api

platform Base

resource /hello as Greeting {

    create()
    read()

}

type Greeting {
    message: String
}

This model:

1. declares the package com.example.joindeworkz.quickstart
2. imports a base API model that defines method types and common types
3. selects the Base platform
4. defines a /hello resource backing onto the Greeting type
5. assigns two methods, create and read, by referencing method types
6. defines the complex type Greeting with a single message property

The imported base model contains, among others, method and type definitions like:

methodtype create POST consumes='*' produces=Id success=201
methodtype read   GET instance=true produces='*' success=200 errorResponse=ErrorResponse

type<string> String(maxLength) maxLength=undefined

These method and type definitions are reused in your own models, so you do not have to repeat low-level HTTP or type details.

Platforms and profiles

A platform describes where and how your model should be realised.

Examples of platforms include:

• Base – a minimal platform that generates OpenAPI and diagrams
• REST + Spring Boot – a platform that generates controllers and persistence
• Messaging + Kafka – a platform for event-driven communication

Platforms are typically defined in platform profile files (often with a .profil extension) using a metamodel that describes:

• which cartridges belong to the platform
• which outlets (e.g. openapi, controller, persistence) should be produced
• configuration options for each cartridge

Your .cmn models simply reference the platform by name:

platform Base

This keeps the domain model free from technology-specific details.

Cartridges and generators

A cartridge is a logical grouping of one or more generators for a platform.

For example, a REST platform might define cartridges such as:

• openapi – generates OpenAPI specifications
• controller – generates Spring Boot controllers
• persistence – generates entities and repositories

Each cartridge, in turn, references 0..n generators:

• generators process the transformed model
• they create concrete files in one or more outlets (e.g. src/generated/resources/openapi, src/generated/java, …)

The mapping is therefore:

• Model → references a Platform
• Platform → defines Cartridges
• Cartridge → references Generators
• Generator → produces artifacts

This layering allows you to:

• reuse platforms and cartridges across projects
• plug in custom generators without changing your models
• combine standard and custom generators for a project

Maven plugin and dependencies

The JoinedWorkz Maven plugin (cmn-maven-plugin) ties everything together in your build:

1. Maven resolves all dependencies on the classpath.
2. The plugin parses all .cmn model files (e.g. from the model directory).
3. The models are transformed into an internal canonical representation.
4. The plugin looks up the referenced platforms, cartridges and generators, which are provided by normal Maven dependencies.
5. The plugin executes the generators and writes the output into configured output directories (such as src/generated/resources/openapi).

Important points:

• The plugin itself is generic: it knows how to parse and transform models, and how to orchestrate generators.
• The actual platform implementations and generator code are provided as regular Maven dependencies. This means you can freely combine standard platforms and custom generators.

In a minimal setup you will often see:

• the generator plugin as a build plugin in the pom.xml
• one or more dependencies that contribute:
  • base models (e.g. common-base)
  • platform definitions
  • cartridges and generators

Tooling: Studio and CLI

You can work with JoinedWorkz in two complementary ways.

JoinedWorkz Studio

A desktop application that provides:

• a rich editor for .cmn models
• syntax highlighting, validation and navigation
• tooling around platforms and generators

Studio is the only component that requires a license key (trial and commercial keys are supported).

Free build tooling

The following parts are freely available and do not require a license:

• the model parser and transformation engine
• the standard generators
• the Maven plugin

You can therefore:

• run JoinedWorkz in CI/CD pipelines
• work purely from the command line if you prefer
• gradually introduce Studio to teams that benefit from a richer editor

Putting it together

A typical workflow looks like this:

1. Model your domain and APIs in .cmn files.
2. Choose or define a platform that matches your target technology stack.
3. Add the generator plugin and required dependencies to your pom.xml.
4. Run Maven to generate code and artifacts.
5. Iterate on the model, platform and generators as your system evolves.

From here, continue with:

• the Quickstart if you have not done it yet, and
• the Modeling and How-to sections for more detailed guidance.