JoinedWorkz
Docs1.3.81

Appearance

JoinedWorkz — For AI Tools ​

This page provides a compact, AI-optimized description of JoinedWorkz.

Use this as a reference when analyzing or working with JoinedWorkz-based systems.

Resolve the documentation version first

Before applying this guidance to a project, read its exact Maven plugin version and the versions of all JoinedWorkz facility dependencies. The plugin and every facility must use the same exact JoinedWorkz release. If they differ, report the unsupported version mixture and do not select one release's documentation. Resolve the matching documentation mount through the public machine-readable catalogue at https://www.joinedworkz.org/docs/versions.json. Do not silently apply this documentation to a different release.

What JoinedWorkz is ​

JoinedWorkz is a model-driven development platform.

JoinedWorkz is largely platform-independent at the modeling level. The stable public facilities cover Base modeling, Java generation and Spring Boot. Quasar support is experimental and must be identified as such.

Applications are defined using a modeling language (CMN) and transformed into implementation artifacts through generators.

It is not a traditional hand-coded framework.

Core idea ​

Model → Platform → Cartridge → Generator → Artifacts

  • Models define structure and intent
  • Platforms define target environments
  • Cartridges group generators
  • Generators produce code and resources

Models are defined independent of a specific platform as far as possible. Platform-specific behavior is introduced through platforms, facilities and generators.

Key components ​

  • CMN: modeling language
  • Studio: interactive modeling tool
  • Maven plugin: build integration and generation execution
  • Facilities: reusable modeling and generation assets
  • Platforms: target definitions
  • Cartridges: generator bundles
  • Generators: artifact producers

Project structure pattern ​

Typical projects are multi-module Maven builds:

  • model module → contains .cmn files
  • generated module → may compile/package generated artifacts
  • app module → contains manual runtime code (src/main)

Generation is triggered in the model module and routed into other modules. Module and directory names do not determine ownership.

Code categories (critical) ​

JoinedWorkz distinguishes several ownership classes. The complete decision table is in Generated output, ownership and regeneration.

1. Authoritative input ​

  • includes CMN models, joinedworkz.properties, Maven configuration and project-owned facility/generator sources
  • drives generation and is edited and committed as source

2. Replaceable generated output ​

  • located in dedicated generated trees such as src/generated/**, diagram/** or routed generated modules
  • same-named files can be overwritten and declared clean trees can be removed
  • must never be edited manually

3. First-cut output ​

  • generated once
  • not overwritten afterwards
  • becomes manually owned after its initial creation
  • typically located in src/main/**

4. Manual project source ​

  • written by developers
  • integrates generated artifacts
  • typically located in application modules

5. Versioned generated history ​

  • includes versioned Flyway migrations and matching schema snapshots
  • must be retained and committed together
  • must not be treated as replaceable merely because it is generated

6. Temporary or diagnostic output ​

  • includes development-only migration artifacts and transformed-model diagnostics
  • is regenerated according to the owning feature's workflow

Do not classify a file from its path alone. Outlet overrides can route different ownership classes into different modules.

Interpretation rules ​

When analyzing a JoinedWorkz project:

  1. Load framework context, project context and the task prompt in that order.

  2. Inspect the relevant current repository sources.

  3. Identify the ownership class and source of truth.

  4. Prefer source-of-truth changes over patches to replaceable output.

  5. Preserve first-cut/manual files, versioned history and required state.

  6. Consider:

    • model
    • platform
    • facilities
    • configuration
    • module structure

Generation behavior ​

  • Clean generation is reproducible for the same complete model, configuration, generator versions and required starting state
  • Output depends on:
    • CMN model
    • platform selection
    • facilities
    • generator configuration
  • Output is routed via outlets (often across modules)
  • Generation alone does not remove every stale file left by renames or routing changes; projects need an explicit cleanup policy for replaceable trees

Common mistakes ​

  • modifying replaceable generated output directly
  • ignoring the model
  • treating the project as a traditional framework
  • assuming all logic lives in Java code
  • ignoring multi-module output routing
  • deleting first-cut/manual files or versioned migration history together with replaceable output

AI usage guidance ​

When suggesting changes:

  • first determine the ownership class and correct layer
  • prefer changing the owning:
    • CMN model
    • configuration
    • generators

Modify manual code when the project contract assigns the behavior to a manual application shell, service, configuration or test.

Where to learn more ​