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 the hub and of modules. Every system built with CodamAI is made of these 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) controls identity and access across the whole system: users, tenants, roles, registration.
• CRMS (CodamAI Reporting Management System) creates reports from templates: PDF, HTML, Word and Excel, with approved templates and tamper-evidently stored documents. More in CRMS.

The hub is the factory. There you create projects, model the data and set up the modules of a project. During the build, your system fetches its models and project scaffold from the hub. After that it runs on its own: the finished system has no hub of its own. The hub itself is built with the same modules as every system it builds.

In the hub you operate the modules through their portals, user interfaces for people: in the CDMS portal you model your data, in the CRMS portal you set up the reports of a project.

CIAS has no administration pages of its own. It controls the entire user and identity logic in the system: users, tenants, roles, groups and registration. For this it offers an admin API (/cias/admin/…). Each portal decides itself what administration looks like: it builds its own presentation on top of this API. The CIAS portal only shows which services are connected to CIAS and how.

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 – the software factory"]
        direction LR
        CP["CDMS portal<br/>modeling"]
        CIP["CIAS portal"]
        CRP["CRMS portal"]
    end
    subgraph SYS["Your system – runs on its own"]
        direction LR
        CDMS["CDMS<br/>the data"]
        CIAS["CIAS<br/>identity and access"]
        CRMS["CRMS<br/>reports from templates"]
    end
    KC["Keycloak<br/>identity provider"]

    HUBG -- "builds" --> SYS
    CDMS -- "embeds or calls" --> CIAS
    CDMS -- "embeds or calls" --> CRMS
    CRMS -- "uses" --> CIAS
    CIAS -- "adapter" --> KC

    classDef hub fill:#4f46e5,stroke:#4f46e5,color:#fff
    classDef sys fill:transparent,stroke:#64748b
    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
    class HUBG hub
    class SYS sys
    class CDMS,CP cdms
    class CIAS,CIP cias
    class CRMS,CRP crms
    class KC idp

The hub builds your system but does not run inside it. Read the arrows inside the system like this: “A CDMS application embeds CIAS or calls it as a separate service.” 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.
• 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.

How the modules fit together

Each module has one job and asks the others only for what it does not know itself. This is how they talk to each other in your running system. The hub does not appear here, its work is done with the build:

flowchart LR
    U["User"]
    KC["Keycloak"]
    CDMS["CDMS<br/>the data"]
    CIAS["CIAS<br/>identity and access"]
    CRMS["CRMS<br/>reports"]

    U -- "signs in,<br/>gets a token" --> KC
    U -- "request with token" --> CDMS
    CDMS -- "who is asking, for which<br/>tenant, with which roles?" --> CIAS
    CDMS -- "template + data:<br/>create a document" --> CRMS
    CRMS -- "who is asking,<br/>which tenants exist?" --> CIAS
    CIAS -- "checks tokens,<br/>maintains roles and groups" --> KC

    classDef user fill:#0f766e,stroke:#0f766e,color:#fff
    classDef idp fill:#c2410c,stroke:#c2410c,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
    class U user
    class KC idp
    class CDMS cdms
    class CIAS cias
    class CRMS crms

Five things stand out:

1. CIAS stands in front of CDMS. Every request first goes through the CIAS filter chain. It checks the token and determines who is asking, for which tenant and with which roles. Only then does CDMS do its work. CDMS uses these roles to check who may read or change which model, see From login to the data.
2. CRMS has no data of its own. It reads nothing from CDMS and writes nothing back. The application fetches the data from CDMS and hands it to CRMS together with the name of the template. How this works is explained in From the click to the report.
3. CRMS asks CIAS. CRMS does not manage people, tenants or roles. It asks CIAS who is making the request and which tenants exist.
4. Only CIAS talks to Keycloak. Keycloak shows the sign-in page and issues tokens. CIAS checks these tokens and writes roles and groups to Keycloak. CDMS and CRMS do not know Keycloak. Why, is explained in CIAS as a bridge to the identity provider.
5. The paths stay the same, however the modules run. CIAS and CRMS can run in the same program as CDMS (embedded) or as a separate service. A method call then becomes an HTTP call. Who asks whom for what does not change, see Embedded and standalone compared and CRMS in the modes of operation.

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
• CRMS in the modes of operation