data-primals-engine 1.7.2 → 1.7.3

package/doc/data-models.md

@@ -1,75 +1,68 @@
-# Data Models: Structuring Your Information
-
-Data Models are the fundamental building blocks in `data-primals-engine`, defining how your application's data is structured and stored. They are essentially blueprints for collections of documents, enabling you to organize and manage diverse types of information.
-
-## What is a Data Model?
-
-In `data-primals-engine`, a data model is a flexible definition of a data entity. Unlike traditional relational databases, models here are schema-less (thanks to MongoDB), meaning you can evolve their structure over time without rigid migration processes. Each model corresponds to a collection in your MongoDB database.
-
-## Defining a Model
-
-Models can be defined either through the platform's user interface or by providing a JSON schema. Key attributes of a model include:
-
--   **`name`** (string, unique): The technical name of the model (e.g., `product`, `user`, `order`). This is used for API interactions and internal references.
--   **`description`** (string): A brief explanation of the model's purpose.
--   **`icon`** (string): An icon (e.g., a Font Awesome class) to visually represent the model in the UI.
--   **`tags`** (array of strings): Keywords for categorization and filtering.
--   **`locked`** (boolean): Indicates if the model is a system model and cannot be modified or deleted via the standard UI (e.g., `user`, `permission`).
--   **`fields`** (array of objects): The core of the model, defining its attributes.
-
-## Fields: The Attributes of a Model
-
-Each field within a model defines a specific piece of data. Fields have various properties to control their type, behavior, and validation:
-
--   **`name`** (string, unique within model): The name of the attribute (e.g., `title`, `price`, `email`).
--   **`type`** (string, required): The data type of the field. Common types include:
-    -   `string`, `string_t` (translatable string)
-    -   `number`
-    -   `boolean`
-    -   `datetime`, `date`
-    -   `email`, `url`, `phone`, `password`
-    -   `richtext`, `richtext_t` (translatable rich text)
-    -   `enum` (predefined list of values)
-    -   `file` (for file uploads)
-    -   `relation` (to link to another model)
-    -   `array` (for lists of values or sub-documents)
-    -   `code` (for storing code snippets, e.g., JSON, JavaScript)
--   **`required`** (boolean): If `true`, the field must have a value.
--   **`unique`** (boolean): If `true`, the field's value must be unique across all documents in the collection.
--   **`default`**: A default value for the field.
--   **`min`, `max`**: Minimum and maximum values for `number` fields, or length for `string` fields.
--   **`relation`** (string, for `relation` type): The name of the model this field relates to.
--   **`multiple`** (boolean, for `relation` type): If `true`, the field can relate to multiple documents in the target model.
--   **`hint`** (string): A helpful description displayed in the UI.
-
-## Example: The `product` Model
-
-The `product` model, defined in `defaultModels.js`, illustrates how fields are used to structure information about a product:
-
-```javascript
-product: {
-    name: 'product',
-    "icon": "FaShoppingBag",
-    "description": "",
-    "tags": ["ecommerce", "products"],
-    fields: [
-        { name: 'name', type: 'string_t', required: true },
-        { name: 'image', type: 'array', itemsType: 'file', mimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'] },
-        { name: 'description', type: 'richtext_t' },
-        { name: 'price', type: 'number', required: true },
-        { name: 'currency', type: 'relation', relation: 'currency', required: true },
-        { name: 'billingFrequency', type: 'enum', items: ['none', 'monthly', 'yearly'] },
-        { name: 'slug', type: 'string', required: true, unique: true },
-        { name: 'brand', type: 'relation', relation: 'brand' },
-        { name: 'category', type: 'relation', relation: 'taxonomy' },
-        { name: 'seoTitle', type: 'string_t' },
-        { name: 'seoDescription', type: 'string_t' }
-    ]
-},
-```
-
-This example shows how a `product` can have a translatable `name`, multiple `image` files, a `price` with a `currency` relation, and be linked to a `brand` and `category` (taxonomy).
-
-By defining models and their fields, you create a robust and adaptable data foundation for your `data-primals-engine` application.
-
-**Next: Data Management**
+# Data Models: Structuring Your Information
+
+Data Models are the fundamental building blocks in `data-primals-engine`, defining how your application's data is structured and stored. They are essentially blueprints for collections of documents, enabling you to organize and manage diverse types of information.
+
+## What is a Data Model?
+
+In `data-primals-engine`, a data model is a flexible definition of a data entity. Unlike traditional relational databases, models here are schema-less (thanks to MongoDB), meaning you can evolve their structure over time without rigid migration processes. Each model corresponds to a collection in your MongoDB database.
+
+## Defining a Model
+
+Models can be defined either through the platform's user interface or by providing a JSON schema. Key attributes of a model include:
+
+| Attribute     | Type                | Description                                                                                             |
+|:--------------|:--------------------|:--------------------------------------------------------------------------------------------------------|
+| **`name`**      | string, unique      | The technical name of the model (e.g., `product`, `user`). Used for API and internal references.        |
+| **`description`** | string              | A brief explanation of the model's purpose.                                                             |
+| **`icon`**      | string              | An icon (e.g., a Font Awesome class) to visually represent the model in the UI.                         |
+| **`tags`**      | array of strings    | Keywords for categorization and filtering.                                                              |
+| **`locked`**    | boolean             | If `true`, the model is a system model and cannot be modified or deleted via the UI.                    |
+| **`fields`**    | array of objects    | The core of the model, defining its attributes.                                                         |
+
+## Fields: The Attributes of a Model
+
+Each field within a model defines a specific piece of data. Fields have various properties to control their type, behavior, and validation:
+
+| Attribute      | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             -
+|:--------------|:--------------------|:--------------------------------------------------------------------------------------------------------|
+| **`name`**       | string    | The name of the attribute (e.g., `title`, `price`, `email`). Unique within the model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   -
+| **`type`**       | string    | The data type of the field. Common types include `string`, `number`, `boolean`, `datetime`, `email`, `richtext`, `enum`, `file`, `relation`, `array`, and `code`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 -
+| **`required`**   | boolean   | If `true`, the field must have a value.                                                                                                                                                                                                                                                                                                                                                                                    -
+| **`unique`**     | boolean   | If `true`, the field's value must be unique across all documents in the collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         -
+| **`default`**    | any       | A default value for the field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              -
+| **`min`, `max`** | number    | Minimum and maximum values for `number` fields, or length for `string` fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             -
+| **`relation`**   | string    | The name of the model this field relates to (for `relation` type).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -
+| **`multiple`**   | boolean   | If `true`, the field can relate to multiple documents in the target model (for `relation` type).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           -
+| **`hint`**       | string    | A helpful description displayed in the UI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    -
+
+## Example: The `product` Model
+
+The `product` model, defined in `defaultModels.js`, illustrates how fields are used to structure information about a product:
+
+```javascript
+product: {
+    name: 'product',
+    "icon": "FaShoppingBag",
+    "description": "",
+    "tags": ["ecommerce", "products"],
+    fields: [
+        { name: 'name', type: 'string_t', required: true },
+        { name: 'image', type: 'array', itemsType: 'file', mimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'] },
+        { name: 'description', type: 'richtext_t' },
+        { name: 'price', type: 'number', required: true },
+        { name: 'currency', type: 'relation', relation: 'currency', required: true },
+        { name: 'billingFrequency', type: 'enum', items: ['none', 'monthly', 'yearly'] },
+        { name: 'slug', type: 'string', required: true, unique: true },
+        { name: 'brand', type: 'relation', relation: 'brand' },
+        { name: 'category', type: 'relation', relation: 'taxonomy' },
+        { name: 'seoTitle', type: 'string_t' },
+        { name: 'seoDescription', type: 'string_t' }
+    ]
+},
+```
+
+This example shows how a `product` can have a translatable `name`, multiple `image` files, a `price` with a `currency` relation, and be linked to a `brand` and `category` (taxonomy).
+
+By defining models and their fields, you create a robust and adaptable data foundation for your `data-primals-engine` application.
+
+**[Next: Data Management](data-management)**

package/doc/roles-permissions.md

@@ -1,43 +1,144 @@
-# Roles and Permissions: Define Who Can See and Do What
-
-The `data-primals-engine` implements a robust Role-Based Access Control (RBAC) system to manage user authorizations. This system relies on two core models: `role` and `permission`, allowing for granular control over what users can access and perform within the platform.
-
-## Permissions
-
-A **Permission** defines a specific action or access right within the system. Permissions can be very broad (e.g., "admin.full_access") or highly specific (e.g., "product.edit").
-
-### Key Fields of the `permission` Model:
-
--   **`name`** (string, required): A unique identifier for the permission (e.g., `model.create`, `product.read`, `user.delete`).
--   **`description`** (richtext, optional): A detailed explanation of what the permission grants.
--   **`filter`** (code - JSON, optional): A JSON filter that restricts the scope of this permission. This is a powerful feature for implementing granular access control. For example, a `product.edit` permission could have a filter `{ "owner": "{_user}" }` to allow a user to only edit products they own. The target model is typically deduced from the permission name (e.g., `product.edit` implies the `product` model).
-
-## Roles
-
-A **Role** is a collection of permissions. Instead of assigning individual permissions to each user, you assign roles, which simplifies management. A user can have multiple roles.
-
-### Key Fields of the `role` Model:
-
--   **`name`** (string, required, unique): The name of the role (e.g., `Administrator`, `Editor`, `Viewer`).
--   **`permissions`** (multiple relation to `permission` model): A list of `permission` documents associated with this role. Any user assigned this role will inherit all its permissions.
-
-## How RBAC Works
-
-1.  **Define Permissions**: Create specific `permission` documents for every action or resource you want to control. Use the `filter` field for fine-grained control.
-2.  **Create Roles**: Group relevant permissions into `role` documents.
-3.  **Assign Roles to Users**: Assign one or more `role` documents to each `user` document.
-
-When a user attempts an action (e.g., accessing an API endpoint or modifying a data entry), the system checks if the user's assigned roles grant them the necessary permissions. If a permission has a `filter`, that filter is applied to the data access query, ensuring the user only interacts with allowed subsets of data.
-
-### User Permissions (Exceptions)
-
-The `userPermission` model allows for exceptions to the standard role-based permissions. This model can grant or revoke specific permissions for an individual user, either permanently or temporarily.
-
--   **`user`** (relation to `user` model): The user for whom the exception applies.
--   **`permission`** (relation to `permission` model): The specific permission being granted or revoked.
--   **`isGranted`** (boolean, required): `true` to grant the permission, `false` to explicitly revoke it.
--   **`expiresAt`** (datetime, optional): If set, the exception is temporary.
-
-This comprehensive RBAC system ensures that your `data-primals-engine` application remains secure and that users only have access to the functionalities and data they are authorized to use.
-
-**Next: Automation with Workflows**
+# Roles and Permissions: Define Who Can See and Do What
+
+The `data-primals-engine` implements a robust Role-Based Access Control (RBAC) system to manage user authorizations. This system relies on two core models: `role` and `permission`, allowing for granular control over what users can access and perform within the platform.
+
+## Understanding the RBAC Flow
+
+The core idea is to assign **Roles** to your **Users**. Each **Role** is a collection of specific **Permissions**. This makes managing rights scalable and easy to understand.
+
+```mermaid
+graph TD
+    subgraph "Core RBAC Flow"
+        U[<i class='fa fa-user'></i> User] -- "Is assigned" --> R(<i class='fa fa-users'></i> Role)
+        R -- "Contains" --> P1[<i class='fa fa-key'></i> Permission: product.create]
+        R -- "Contains" --> P2[<i class='fa fa-key'></i> Permission: product.read]
+    end
+
+    subgraph "Exception Mechanism"
+        U -- "Can have direct" --> UP(<i class='fa fa-user-check'></i> userPermission)
+        UP -- "Grants/Revokes" --> P3[<i class='fa fa-key'></i> Permission: product.delete]
+    end
+
+    style U fill:#cde,color:#000,stroke:#333,stroke-width:2px
+    style R fill:#dcf,color:#000,stroke:#333,stroke-width:2px
+    style P1 fill:#fcd,color:#000,stroke:#333,stroke-width:2px
+    style P2 fill:#fcd,color:#000,stroke:#333,stroke-width:2px
+    style P3 fill:#fcd,color:#000,stroke:#333,stroke-width:2px
+    style UP fill:#fec,color:#000,stroke:#333,stroke-width:2px
+```
+
+## How to Set Up Permissions: A Step-by-Step Guide
+
+Here is a practical guide to setting up your access control using API calls.
+
+### Step 1: Define Your Permissions
+
+A **Permission** defines a specific action. The engine uses a clear naming convention for API access, including explicit denials (`NOT_`) which override broader permissions:
+-   `API_ADD_DATA`: Allows creating data in *any* model.
+-   `API_ADD_DATA_product`: Allows creating data *only* in the `product` model.
+-   `API_ADD_DATA_NOT_user`: Explicitly denies creating data in the `user` model, even if `API_ADD_DATA` is granted.
+-   `API_SEARCH_DATA`: Allows reading data from *any* model.
+-   `API_SEARCH_DATA_NOT_user`: Explicitly denies searching data in the `user` model.
+-   `API_EDIT_DATA_order`: Allows editing data *only* in the `order` model.
+-   `API_EDIT_DATA_NOT_user`: Explicitly denies editing data in the `user` model.
+-   `API_DELETE_DATA`: Allows deleting data from *any* model.
+-   `API_DELETE_DATA_NOT_user`: Explicitly denies deleting data in the `user` model.
+-   `API_ADMIN`: A super-permission that grants all rights.
+
+**Example: Creating permissions for a "Product Manager"**
+
+```javascript
+await insertData('permission', [
+  // General permission to view products
+  { name: 'API_SEARCH_DATA_product', description: 'Allows viewing all products.' },
+  // Permission to create new products
+  { name: 'API_ADD_DATA_product', description: 'Allows creating new products.' },
+  // Permission to edit ONLY products they own
+  {
+    name: 'API_EDIT_DATA_product',
+    description: 'Allows editing of one\'s own products.',
+    filter: { "$eq": ["$createdBy", "{user._id}"] } // Dynamic filter
+  }
+]);
+```
+
+### Step 2: Create Roles and Assign Permissions
+
+A **Role** is a collection of permissions. Instead of assigning dozens of individual permissions to each user, you assign them a role.
+
+**Example: Creating the "Product Manager" role**
+
+We use the `$link` operator to associate the permissions we created in the previous step.
+
+```javascript
+await insertData('role', {
+  name: 'Product Manager',
+  permissions: {
+    "$link": {
+      // Find permissions whose name is in the following list
+      "$in": ["$name", [
+        "API_SEARCH_DATA_product",
+        "API_ADD_DATA_product",
+        "API_EDIT_DATA_product"
+      ]],
+      "_model": "permission" // Specify the model to search in
+    }
+  }
+});
+```
+
+### Step 3: Assign a Role to a User
+
+Finally, you assign the newly created role to a user by updating their `roles` field.
+
+**Example: Making "John Doe" a Product Manager**
+
+```javascript
+await editData('user', 
+  { username: 'john.doe' }, // Filter to find the user
+  {
+    // Use $link to find the role by its name
+    roles: { "$link": { "name": "Product Manager", "_model": "role" } }
+  }
+);
+```
+
+Now, `john.doe` has all the permissions defined in the "Product Manager" role.
+
+## Advanced: Exceptions with `userPermission`
+
+Sometimes, you need to grant or revoke a specific permission for a single user without creating a whole new role. The `userPermission` model is perfect for this.
+
+### Key Fields of the `userPermission` Model
+
+| Attribute | Type | Description |
+|:---|:---|:---|
+| **`user`** | relation to `user` | The user for whom the exception applies. |
+| **`permission`** | relation to `permission` | The specific permission being granted or revoked. |
+| **`isGranted`** | boolean | `true` to grant the permission, `false` to explicitly revoke it. |
+| **`expiresAt`** | datetime | If set, the exception is temporary and will automatically expire. |
+
+**Example: Temporarily grant "John Doe" the right to delete products for 24 hours.**
+
+```javascript
+// First, ensure the 'API_DELETE_DATA_product' permission exists
+await insertData('permission', {
+  name: 'API_DELETE_DATA_product',
+  description: 'Allows deleting products.'
+});
+
+// Now, create the temporary exception
+const expirationDate = new Date();
+expirationDate.setDate(expirationDate.getDate() + 1); // Expires tomorrow
+
+await insertData('userPermission', {
+  user: { "$link": { "username": "john.doe", "_model": "user" } },
+  permission: { "$link": { "name": "API_DELETE_DATA_product", "_model": "permission" } },
+  isGranted: true,
+  expiresAt: expirationDate.toISOString()
+});
+```
+
+This comprehensive RBAC system ensures that your application remains secure and that users only have access to the functionalities and data they are authorized to use.
+
+**[Next: Automation with Workflows](automation-workflows)**