The project scaffold

What this is about

You do not start a new CDMS project with an empty folder. The hub gives you a project scaffold: a ZIP with a POM, a main class, configuration and the current model. You unpack it, build once, and the application runs.

What exactly is in the scaffold depends on a few settings of the system in the hub: Which database does it use? Does it need login? Does CIAS run in the same process? Each setting is a branch that adds dependencies, configuration and sometimes classes.

How you get the scaffold

What is in the ZIP

katalog/
├── pom.xml                         ← parent cdms-app-parent, dependencies per branch
├── README.md                       ← building, starting, all environment variables
├── cdms-generator.properties       ← access to the hub for the build (secret empty)
├── .env.example                    ← runtime variables: database, tenant mode, CIAS …
├── .gitignore
├── .cache/                         ← the model as YAML, so the first build works offline
│   ├── system.yaml
│   └── models.yaml …
└── src/
    ├── main/java/com/codamai/shop/katalog/
    │   ├── Start.java              ← Spring Boot main class
    │   └── config/                 ← only with CIAS EMBEDDED: three wiring classes
    ├── main/resources/application.yaml
    └── test/java/…/TenantContextArchitectureTest.java   ← only with login (OIDC)

The hub derives the Maven coordinates from the names. The project “Shop” and the system “Katalog” become groupId com.codamai.shop, artifactId katalog and the base package com.codamai.shop.katalog.

The branches

The settings are on the system in the hub, the placement of the CIAS module on the project. The build reads them later from .cache/system.yaml and .cache/cias.yaml. Maven or Spring properties do not switch the branches.

flowchart TD
    A{"authentication"} -- "NONE" --> N["no login<br/>CIAS is always NONE"]
    A -- "OIDC" --> O["+ CIAS filter chain<br/>+ architecture test<br/>+ CIAS_ISSUER, CIAS_CLIENT …"]
    O --> C{"runtime of the<br/>CIAS module"}
    C -- "another one" --> R["REMOTE<br/>+ CIAS tenant client<br/>CIAS runs elsewhere"]
    C -- "the system's" --> E["EMBEDDED<br/>+ tenant, user and<br/>role management, Keycloak adapter<br/>+ block codamai.cias, cias-configuration.yaml<br/>+ 3 classes under config/"]
    C -- "none / no module" --> X["build refused (400)"]
    D{"database"} -- "MYSQL" --> D1["mysql-connector-j"]
    D -- "MARIADB" --> D2["mariadb-java-client"]
    S{"storage"} -- "FILESYSTEM" --> S1["+ file storage building block<br/>+ basePath /files/"]
    S -- "NONE" --> S0["no files"]
    M{"monitoring"} -- "ACTUATOR" --> M1["+ Prometheus, AOP<br/>+ metrics and probes on 8081"]
    M -- "NONE" --> M0["basic Actuator setup only<br/>on 8081"]
    U{"a model audited?"} -- "yes" --> U1["+ hibernate-envers"]

Whether the application serves one tenant or many is not a branch of the scaffold. CODAMAI_PERSISTENCE_TENANT_MODE (SINGLE or MULTI) decides this at runtime, see Single- or multi-tenant.

An example

<parent>
  <groupId>com.codamai.cdms</groupId>
  <artifactId>cdms-app-parent</artifactId>
</parent>
<properties>
  <cdms.main.class>com.codamai.shop.katalog.Start</cdms.main.class>
  <cdms.generator.fetch.skip>false</cdms.generator.fetch.skip>
</properties>
<dependencies>
  <!-- cdms-managed:dependencies:start -->
  … core: cdms-rest-api, cdms-system-layer, cdms-database …
  hibernate-envers               ← auditing
  mysql-connector-j              ← database: MYSQL
  cdms-localfs-storage           ← storage: FILESYSTEM
  cias-authentication            ← authentication: OIDC
  micrometer-registry-prometheus ← monitoring: ACTUATOR
  cias-tenancy-client            ← CIAS module in another runtime
  <!-- cdms-managed:dependencies:end -->
</dependencies>

spring:
  application: { name: katalog }
  threads: { virtual: { enabled: true } }
codamai:
  cdms:
    api: { createReadMode: STRICT }
    persistence:                         ← storage: FILESYSTEM
      file:
        basePath: ${CODAMAI_CDMS_PERSISTENCE_FILE_BASE_PATH:/files/}
management:
  server: { port: 8081 }
  endpoints: { web: { exposure: { include: health, info, metrics, prometheus } } }   ← monitoring: ACTUATOR

Created once, then yours

What happens to the files when you build later or download the scaffold again?

Two consequences:

• Changing a branch later (for example storage to FILESYSTEM) affects the POM on the next build: the dependency is added, and deselected ones are removed. You add the matching configuration in application.yaml and .env yourself. The README of a fresh scaffold shows you what has to go there.
• A new download is a new ZIP. Nothing is merged with your project. Take from it what you need.

You turn off POM maintenance with CODEGEN_POM_GENERATE=false.

Pitfalls