The CodamAI modules

What this is about

CodamAI is the software factory of Codamic AG. You use it to build business applications without starting from zero every time. CodamAI consists of several modules. Each module has one clearly separated job:

• CDMS (CodamAI Data Management System) manages the data: models, REST API, database, files, history.
• CIAS (CodamAI Identity & Access System) handles identity and access: users, tenants, roles, registration.
• CRMS (CodamAI Reporting Management System) creates reports from templates.
• The hub is the central user interface with its backend. There you create projects, model your data and manage access.

Below them are shared building blocks that all Java modules use. Next to everything stands Keycloak, the identity provider. That is where people sign in.

The module map

Each module has a fixed color. You see the same colors on every page of this documentation.

flowchart TB
    subgraph HUBG["Hub"]
        direction LR
        HF["Hub user interface<br/>hub-frontend"]
        HB["Hub backend<br/>hub-backend<br/>+ MCP server"]
    end
    CP["CDMS portal<br/>modeling"]
    CIP["CIAS portal"]
    CDMS["CDMS<br/>data layer, generator,<br/>project scaffold"]
    CIAS["CIAS<br/>identity and access"]
    CRMS["CRMS<br/>reports from templates"]
    KC["Keycloak<br/>identity provider"]
    G["Shared building blocks<br/>global-parent, commons,<br/>commons-persistence"]

    HF --> HB
    CP --> HB
    CIP --> HB
    HB -- "is built with" --> CDMS
    HB -- "embeds" --> CIAS
    CRMS -- "is built with" --> CDMS
    CRMS -- "uses" --> CIAS
    CIAS -- "adapter" --> KC
    CDMS --> G
    CIAS --> G

    classDef hub fill:#4f46e5,stroke:#4f46e5,color:#fff
    classDef cdms fill:#1976d2,stroke:#1976d2,color:#fff
    classDef cias fill:#8e24aa,stroke:#8e24aa,color:#fff
    classDef crms fill:#ffc107,stroke:#b38600,color:#1f1a00
    classDef idp fill:#c2410c,stroke:#c2410c,color:#fff
    classDef shared fill:#64748b,stroke:#64748b,color:#fff
    class HF,HB hub
    class CDMS,CP cdms
    class CIAS,CIP cias
    class CRMS crms
    class KC idp
    class G shared

Read the arrows like this: “The hub backend is built with CDMS and embeds CIAS.” Embedding means: CIAS runs as a building block inside the same program, not as a separate service. What that means is explained in Embedded and standalone compared.

The modules one by one

A few words from the table:

• A model describes a kind of thing your application knows, for example “customer” with its fields. More in Modeling in the hub.
• A tenant is a customer of your application whose data is separated from everyone else’s.
• A hook is your own code that plugs into a CDMS process.
• MCP (Model Context Protocol) is a protocol through which AI clients call tools. The hub’s MCP server lets them read models and change them in a controlled way, see Schema change through the MCP server.

The map of the repositories

Each module consists of several repositories, that is, separate Git projects. There are four kinds:

• Library: a Java building block (JAR) that other projects include. It never runs on its own.
• Service: a program that starts on its own and answers requests.
• User interface: a web application (Nuxt) with its own server, the BFF. What a BFF is, is described in The parties in a request.
• Tool: something that runs during the build, in tests, or inside Keycloak.

flowchart LR
    subgraph GEM["Shared"]
        direction TB
        gp["global-parent"]
        co["commons"]
        cpe["commons-persistence"]
    end
    subgraph CD["CDMS"]
        direction TB
        cdl["cdms-commons · cdms-rest-api<br/>cdms-system-layer · cdms-authorization<br/>cdms-persistence-database<br/>cdms-localfs-storage"]
        cdw["cdms-generator · cdms-scaffold<br/>cdms-parent · cdms-integrationtest"]
        cdf["CDMS/frontend<br/>(CDMS portal)"]
    end
    subgraph CI["CIAS"]
        direction TB
        cil["cias-kernel · cias-authentication<br/>cias-tenancy · cias-user<br/>cias-authorization · cias-registration<br/>cias-notification · cias-audit<br/>cias-iam-api · cias-iam-keycloak<br/>cias-iam-memory · cias-tenancy-client<br/>cias-spring-boot-starter"]
        cir["cias-runtime"]
        ciw["cias-parent · cias-test-support<br/>cias-integrationtest<br/>cias-iam-keycloak-provider"]
        cif["cias-frontend<br/>(CIAS portal)"]
    end
    subgraph HU["Hub"]
        direction TB
        hb["hub-backend"]
        hf["hub-frontend"]
        hl["hub-login"]
    end
    subgraph CR["CRMS"]
        direction TB
        crb["crms-backend-mvp"]
        crf["crms-frontend-mvp"]
    end

    classDef hub fill:#4f46e5,stroke:#4f46e5,color:#fff
    classDef cdms fill:#1976d2,stroke:#1976d2,color:#fff
    classDef cias fill:#8e24aa,stroke:#8e24aa,color:#fff
    classDef crms fill:#ffc107,stroke:#b38600,color:#1f1a00
    classDef shared fill:#64748b,stroke:#64748b,color:#fff
    class gp,co,cpe shared
    class cdl,cdw,cdf cdms
    class cil,cir,ciw,cif cias
    class hb,hf,hl hub
    class crb,crf crms

Shared building blocks

CDMS

CIAS

Hub

CRMS

Documentation

How the modules fit together

Dependencies always point downward: an application includes libraries, libraries include the shared building blocks. Never the other way round.

flowchart BT
    GP["global-parent"]
    CO["commons"]
    CPE["commons-persistence"]
    CDL["CDMS libraries"]
    CIL["CIAS libraries"]
    GEN["cdms-generator<br/>(during the build)"]
    HB["hub-backend"]
    CRB["crms-backend-mvp"]
    APP["your CDMS application"]
    CIR["cias-runtime"]

    CO --> GP
    CPE --> CO
    CDL --> CO
    CDL --> CPE
    CIL --> CO
    CIL --> CPE
    HB --> CDL
    HB --> CIL
    CRB --> CDL
    CRB --> CIL
    APP --> CDL
    APP --> CIL
    CIR --> CIL
    GEN -. "creates code for" .-> HB
    GEN -. "creates code for" .-> CRB
    GEN -. "creates code for" .-> APP

    classDef hub fill:#4f46e5,stroke:#4f46e5,color:#fff
    classDef cdms fill:#1976d2,stroke:#1976d2,color:#fff
    classDef cias fill:#8e24aa,stroke:#8e24aa,color:#fff
    classDef crms fill:#ffc107,stroke:#b38600,color:#1f1a00
    classDef shared fill:#64748b,stroke:#64748b,color:#fff
    classDef build fill:#57534e,stroke:#57534e,color:#fff
    class GP,CO,CPE shared
    class CDL,APP cdms
    class CIL,CIR cias
    class HB hub
    class CRB crms
    class GEN build

Three things stand out:

1. Every CDMS application is built the same way. The hub backend, the CRMS backend and your own application include the same CDMS libraries. The generator creates the code from their model for all three. It fetches the models of your application from the hub, see Code generation in the build.
2. CIAS comes as libraries. An application with sign-in includes cias-authentication, so that every request goes through the filter chain. Whether the other CIAS modules run in the same process or in cias-runtime is the operating mode, see Embedded and standalone compared.
3. Only one module knows Keycloak. Only the adapter cias-iam-keycloak talks to the Keycloak admin API. Why, is explained in CIAS as a bridge to the identity provider.

Which kind of repository is this?

Pitfalls

Next

• The parties in a request: who talks to whom in a request
• The key terms in pictures
• Who decides what?
• Embedded and standalone compared