CodamAIDocs

Legend

What the pictures on these pages mean and how to read them.

All pages use the same kinds of pictures. Each one has one job, and once you have read them, you can read every page.

Colors of the parties

Each party has the same color everywhere:

  1. 1
    User
    a human in front of a screen
  2. 2
    Client
    the program that calls the API, that is frontend, BFF or another server
  3. 3
    CDMS
    the data layer with REST API, system layer and persistence
  4. 4
    CIAS
    identity and access, plus the filter chain that checks every token
  5. 5
    Keycloak
    the identity provider. It checks passwords and issues the tokens
  6. 6
    Database
    system database, tenant database or file storage
  7. 7
    Email
    an email sent to a person
  8. 8
    Hook
    the project's own business logic that hooks into the flow
  9. 9
    Hub
    the modeling interface with its MCP server. This is where the models live
  10. 10
    Build
    the project's Maven build with the code generator

Steps

A flow from top to bottom. The colored label says who acts, the arrow says to whom they turn. A dashed circle with ? stands for a check, a red box for an error exit, a green one for the end.

  1. 1
    Client→CDMS
    sends POST /crm/customer/create
  2. 2
    CDMS
    checks whether the role for “create” is in the token
  3. 3
    CDMS
    role missing → response 403
  4. 4
    CDMS→Database
    writes the new row
    Result: object created, response 200 with the requested fields

Stations

A request travels through several stations. At each station, something is checked. On the right you see what happens when the check does not pass. Only a request that passes all stations reaches the green goal.

Example of a request through three stations
  1. CIAS
    Filter chain
    Is the token valid?
    ↳ no 401 – renew the token
  2. CDMS
    Permission check
    May this role read the model?
    ↳ no 403
  3. CDMS
    Row filter
    Does the object belong to your own tenant?
    ↳ no 404 – as if the object did not exist
  4. Data is delivered

Variants

Many flows come in several variants. Each variant is its own tab. When says in which situation this variant applies.

Example with two variants

When: the normal case

  1. 1
    Client
    does something
  2. 2
    CDMS
    answers

When: a special case

Here the flow differs, exactly at this point.

Result: different result

Decision table

When several conditions together decide the result, each combination is its own row. The last column is the result. “–” means: does not matter here.

Role present?Target allowed?What happens
no–Switch is silently ignored
yesno403
yesyesSwitch takes effect

Comparison

Two or more things side by side that are easy to mix up.

PUT
replaces
  • What is missing gets cleared
  • describes the whole target state
PATCH
changes
  • What is missing stays unchanged
  • names only the change

Field selection

Which fields a request hits. Gray means “not delivered”, colored means “delivered”. References have a dotted border and come only with their id.

simple fieldreferencereturned
RequestResult
"+"
firstnamelastnamecompany
"*"
firstnamelastnamecompany (id only)

Request and response

Request
POST /api/rest/crm/customer/read/42
{ "response": ["id", "name"] }
Response
{ "data": { "id": "42", "name": "Muster GmbH" }, "meta": { "error": false } }

Sequence diagrams

For flows with back and forth between several parties, we use Mermaid sequence diagrams. Each vertical line is a party, and time runs downward. A solid arrow is a request, a dashed one is the response. The numbers show the order.

sequenceDiagram
    participant C as Client
    participant D as CDMS
    participant DB as Database
    C->>D: POST /query
    D->>DB: SELECT … WHERE …
    DB-->>D: rows
    D-->>C: data + meta

Boxes

Search