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 build reads them later from .cache/system.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-authentication<br/>+ architecture test<br/>+ CIAS_ISSUER, CIAS_CLIENT …"]
    O --> C{"cias"}
    C -- "REMOTE" --> R["+ cias-tenancy-client<br/>CIAS runs as a separate service"]
    C -- "EMBEDDED" --> E["+ cias-tenancy, cias-user,<br/>cias-authorization, cias-iam-keycloak<br/>+ block codamai.cias<br/>+ 3 classes under config/"]
    C -- "NONE" --> X["no CIAS tenant service"]
    D{"database"} -- "MYSQL" --> D1["mysql-connector-j"]
    D -- "MARIADB" --> D2["mariadb-java-client"]
    S{"storage"} -- "FILESYSTEM" --> S1["+ cdms-localfs-storage<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: REMOTE
  <!-- 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