JoinedWorkz
Docs1.3.80

Appearance

CMN — For AI Tools ​

This page provides a compact, AI-optimized overview of the CMN modeling language used in JoinedWorkz.

Use this as a guide when analyzing or modifying CMN models.

What CMN is ​

CMN (Canonical Model Notation) is the modeling language of JoinedWorkz.

It describes:

  • domain types
  • APIs
  • resources
  • application structure

CMN defines system intent, not implementation details.

Key principle ​

CMN is model-driven, not code-driven.

Do not think in Java classes or database tables.

Think in:

  • domain concepts
  • APIs
  • structure
  • behavior

Basic structure of a model ​

A typical .cmn file contains:

cmn
package com.example.project

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

platform SpringBoot

type Example {
    field: String
}

resource /example as Example {
    create()
    read()
}

Core elements ​

Package ​

Defines the namespace:

cmn
package com.example.project

Import ​

Imports reusable definitions from facilities:

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

Platform ​

Defines the target environment:

cmn
platform SpringBoot

Type ​

Defines a domain structure:

cmn
type Request {
    id: Long
    description: String
}

Resource ​

Defines an API endpoint:

cmn
resource /requests as Request {
    create()
    read()
    update()
}

Modeling rules ​

1. Model intent, not implementation ​

Good:

  • domain structure
  • API shape

Bad:

  • database details
  • framework-specific annotations

2. Keep models simple ​

  • prefer clear, flat structures
  • avoid unnecessary complexity

3. Separate concerns ​

Use different files for:

  • domain
  • API
  • application
  • configuration

4. Use platform abstraction ​

  • avoid hardcoding technology details
  • use platform and facilities instead

Common patterns ​

CRUD resource ​

cmn
resource /requests as Request {
    create()
    read()
    update()
}

Domain type ​

cmn
type User {
    id: Long
    name: String
}

Common mistakes ​

Thinking in Java ​

Wrong:

  • adding implementation details
  • designing classes instead of models

Editing generated code instead of model ​

Fix:

  • update CMN model
  • regenerate

Mixing concerns ​

Wrong:

  • domain + API + runtime logic in one place

Over-specifying ​

Wrong:

  • too many fields
  • too much structure too early

AI usage guidance ​

When modifying CMN:

  1. Identify the correct element:

    • type
    • resource
    • platform

  2. Keep changes minimal and consistent.

  3. Do not introduce implementation details.

  4. Prefer extending existing models over duplicating them.

Relationship to generation ​

CMN does not define code directly.

It defines:

  • structure
  • intent

Generation produces:

  • Java code
  • APIs
  • database migrations
  • other artifacts

Summary ​

CMN is:

  • declarative
  • model-driven
  • platform-independent as far as possible

Use it to define what the system is, not how it is implemented.