Model levels: system, tenant, user

What this is about

When you create a model in the hub, the first thing you choose is its scope, the level its data lives on. There are exactly three:

Where the data lives

In operating mode MULTI, every tenant has a database of its own. The user level is not a separate database but a refinement inside the tenant database:

flowchart LR
    subgraph SYS["System database"]
        S1["System models<br/>e.g. country list"]
    end
    subgraph TA["Database of tenant A"]
        A1["Tenant models<br/>e.g. customers of A"]
        A2["User models<br/>Anna's rows | Ben's rows"]
    end
    subgraph TB2["Database of tenant B"]
        B1["Tenant models<br/>e.g. customers of B"]
        B2["User models<br/>Clara's rows"]
    end
    SYS ~~~ TA ~~~ TB2

User models have an additional field _userId. On create, CDMS writes the ID of the signed-in person into it, and on read it filters by it.

Which level do I choose?

Two questions are enough:

flowchart LR
    Q1{"Do all customers need<br/>the same data?"}
    Q1 -->|yes| SYS["System"]
    Q1 -->|no| Q2{"Does the data belong to<br/>a single person who is the<br/>only one allowed to see it?"}
    Q2 -->|yes| USR["User"]
    Q2 -->|no| TEN["Tenant"]

What happens on an access

The level takes effect on every read and write, in two places: choosing the database and filtering the rows.

Which database? The complete decision

This is how the persistence layer decides on every single access. The order matters: the question “system model?” comes before everything else.

“Allowed” means: the tenant is in the allowedTenants list from the token. If the list is missing, nothing is allowed.

The table shows the view of the persistence layer. In MULTI, a request without a tenant usually never gets that far: the CIAS filter chain already rejects it with 403 tenant-required. The 400 is the second safeguard behind it.

There is no fallback: if the tenant is missing, a tenant object never silently ends up in the system database. Whether a tenant is served at all (active, not suspended) has already been decided before, by the tenant gate in CIAS.

SINGLE and MULTI

The levels exist in both operating modes. Only the way data is stored changes:

Relations between levels

A relation connects two models, and both must be reachable in the same database. That leads to the rule the hub enforces while you model:

In the hub, invalid targets are grayed out in the selection (“scope not allowed”) and rejected on save.

How the level is set

Two safeguards against mix-ups

Two independent mechanisms prevent an object from ending up in the wrong database:

What else depends on the level

Roles, attribute filters and custom filters apply in addition on every level.

Pitfalls