data-primals-engine 1.6.3 → 1.6.5

package/client/package-lock.json

@@ -7,6 +7,7 @@
     "": {
       "name": "client",
       "version": "0.0.0",
+      "hasInstallScript": true,
       "dependencies": {
         "@babel/runtime": "^7.28.3",
         "@codeium/react-code-editor": "^1.0.12",
@@ -1134,7 +1135,7 @@
         "globals": "^14.0.0",
         "ignore": "^5.2.0",
         "import-fresh": "^3.2.1",
-        "js-yaml": "^4.1.0",
+        "js-yaml": ">=4.1.1",
         "minimatch": "^3.1.2",
         "strip-json-comments": "^3.1.1"
       },
@@ -3223,23 +3224,28 @@
       }
     },
     "node_modules/body-parser": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.0.tgz",
-      "integrity": "sha512-02qvAaxv8tp7fBa/mw1ga98OGm+eCbqzJOKoRt70sLmfEEi+jyBYVTDGfCL/k06/4EMk/z01gCe7HoCH/f2LTg==",
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.1.tgz",
+      "integrity": "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw==",
+      "license": "MIT",
       "peer": true,
       "dependencies": {
         "bytes": "^3.1.2",
         "content-type": "^1.0.5",
-        "debug": "^4.4.0",
+        "debug": "^4.4.3",
         "http-errors": "^2.0.0",
-        "iconv-lite": "^0.6.3",
+        "iconv-lite": "^0.7.0",
         "on-finished": "^2.4.1",
         "qs": "^6.14.0",
-        "raw-body": "^3.0.0",
-        "type-is": "^2.0.0"
+        "raw-body": "^3.0.1",
+        "type-is": "^2.0.1"
       },
       "engines": {
         "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/brace-expansion": {
@@ -3323,6 +3329,7 @@
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
       "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+      "license": "MIT",
       "peer": true,
       "engines": {
         "node": ">= 0.8"
@@ -3766,9 +3773,10 @@
       "integrity": "sha512-oaMBel6gjolK862uaPQOVTA7q3TZhuSvuMQAAglQDOWYO9A91IrAOUJEyKVlqJlHE0vq5p5UXxzdPfMH/x6xNg=="
     },
     "node_modules/debug": {
-      "version": "4.4.1",
-      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz",
-      "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==",
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
       },
@@ -4440,7 +4448,7 @@
       "peer": true,
       "dependencies": {
         "accepts": "^2.0.0",
-        "body-parser": "^2.2.0",
+        "body-parser": ">=2.2.1",
         "content-disposition": "^1.0.0",
         "content-type": "^1.0.5",
         "cookie": "^0.7.1",
@@ -5020,19 +5028,24 @@
       }
     },
     "node_modules/http-errors": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz",
-      "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==",
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
+      "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==",
+      "license": "MIT",
       "peer": true,
       "dependencies": {
-        "depd": "2.0.0",
-        "inherits": "2.0.4",
-        "setprototypeof": "1.2.0",
-        "statuses": "2.0.1",
-        "toidentifier": "1.0.1"
+        "depd": "~2.0.0",
+        "inherits": "~2.0.4",
+        "setprototypeof": "~1.2.0",
+        "statuses": "~2.0.2",
+        "toidentifier": "~1.0.1"
       },
       "engines": {
         "node": ">= 0.8"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/i18next": {
@@ -5067,15 +5080,20 @@
       }
     },
     "node_modules/iconv-lite": {
-      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
-      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.0.tgz",
+      "integrity": "sha512-cf6L2Ds3h57VVmkZe+Pn+5APsT7FpqJtEhhieDCvrE2MK5Qk9MyffgQyuxQTm6BChfeZNtcOLHp9IcWRVcIcBQ==",
+      "license": "MIT",
       "peer": true,
       "dependencies": {
         "safer-buffer": ">= 2.1.2 < 3.0.0"
       },
       "engines": {
         "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
       }
     },
     "node_modules/ignore": {
@@ -5575,15 +5593,16 @@
       "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="
     },
     "node_modules/js-yaml": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
-      "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
       "dev": true,
+      "license": "MIT",
       "dependencies": {
         "argparse": "^2.0.1"
       },
       "bin": {
-        "js-yaml": "bin/js-yaml.js"
+        "js-yaml": ">=4.1.1"
       }
     },
     "node_modules/jsesc": {
@@ -6559,18 +6578,19 @@
       }
     },
     "node_modules/raw-body": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz",
-      "integrity": "sha512-RmkhL8CAyCRPXCE28MMH0z2PNWQBNk2Q09ZdxM9IOOXwxwZbN+qbWaatPkdkWIKL2ZVDImrN/pK5HTRz2PcS4g==",
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz",
+      "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==",
+      "license": "MIT",
       "peer": true,
       "dependencies": {
-        "bytes": "3.1.2",
-        "http-errors": "2.0.0",
-        "iconv-lite": "0.6.3",
-        "unpipe": "1.0.0"
+        "bytes": "~3.1.2",
+        "http-errors": "~2.0.1",
+        "iconv-lite": "~0.7.0",
+        "unpipe": "~1.0.0"
       },
       "engines": {
-        "node": ">= 0.8"
+        "node": ">= 0.10"
       }
     },
     "node_modules/react": {
@@ -6952,7 +6972,7 @@
         "highlight.js": "^10.4.1",
         "highlightjs-vue": "^1.0.0",
         "lowlight": "^1.17.0",
-        "prismjs": "^1.27.0",
+        "prismjs": ">=1.30.0",
         "refractor": "^3.6.0"
       },
       "peerDependencies": {
@@ -7068,7 +7088,7 @@
       "dependencies": {
         "hastscript": "^6.0.0",
         "parse-entities": "^2.0.0",
-        "prismjs": "~1.27.0"
+        "prismjs": ">=1.30.0"
       },
       "funding": {
         "type": "github",
@@ -7167,15 +7187,6 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/refractor/node_modules/prismjs": {
-      "version": "1.27.0",
-      "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.27.0.tgz",
-      "integrity": "sha512-t13BGPUlFDR7wRB5kQDG4jjl7XeuH6jbJGt11JHPL96qwsEHNX2+68tFXqc1/k+/jALsbSWJKUOT/hcYAZ5LkA==",
-      "peer": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/regexp.prototype.flags": {
       "version": "1.5.4",
       "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.4.tgz",
@@ -7422,6 +7433,7 @@
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT",
       "peer": true
     },
     "node_modules/sass": {
@@ -8021,9 +8033,10 @@
       "integrity": "sha512-HTEHMNieakEnoe33shBYcZ7NX83ACUjCu8c40iOGEZsngj9zRnkqS9j1pqQPXwobB0ZcVTk27REb7COQ0UR59w=="
     },
     "node_modules/statuses": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz",
-      "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
+      "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==",
+      "license": "MIT",
       "peer": true,
       "engines": {
         "node": ">= 0.8"
@@ -8440,6 +8453,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
       "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==",
+      "license": "MIT",
       "peer": true,
       "engines": {
         "node": ">= 0.8"
@@ -8808,4 +8822,4 @@
       }
     }
   }
-}
+}

package/client/package.json

@@ -4,6 +4,7 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
+    "preinstall": "npx force-resolutions",
     "dev": "vite",
     "build": "vite build --mode development",
     "build:ssr-client": "vite build --ssrManifest --outDir dist/client --mode development",
@@ -11,6 +12,11 @@
     "lint": "eslint .",
     "preview": "vite preview"
   },
+  "resolutions": {
+    "body-parser": ">=2.2.1",
+    "js-yaml": ">=4.1.1",
+    "prismjs": ">=1.30.0"
+  },
   "peerDependencies": {
     "@tiptap/react": "^2.26.1",
     "react-chartjs-2": "^5.3.0",

package/client/src/App.scss

@@ -5,6 +5,35 @@ img {
   width: auto;
 }
 
+/*
+ * Style global pour les barres de défilement (scrollbars)
+ * S'applique à toute l'application, y compris les blocs de code.
+ */
+
+/* Pour les navigateurs WebKit (Chrome, Safari, Edge, etc.) */
+::-webkit-scrollbar {
+  width: 8px;  /* Largeur de la scrollbar verticale */
+  height: 8px; /* Hauteur de la scrollbar horizontale */
+}
+
+/* La piste (le fond de la scrollbar) */
+::-webkit-scrollbar-track {
+  background: $scrollbar-track-color;
+  border-radius: 10px;
+}
+
+/* La poignée (la partie mobile de la scrollbar) */
+::-webkit-scrollbar-thumb {
+  background-color: $scrollbar-thumb-color;
+  border-radius: 10px;
+  border: 2px solid $scrollbar-track-color; /* Crée un petit espacement autour de la poignée */
+}
+
+/* La poignée au survol de la souris */
+::-webkit-scrollbar-thumb:hover {
+  background-color: $scrollbar-thumb-hover-color;
+}
+
 body {
   font-family: "Nunito Sans", sans-serif;
   line-height: 1.6; // Améliore la lisibilité

package/client/src/_variables.scss

@@ -17,5 +17,8 @@ $danger-color: #ff1e00;
 $shadow-color: rgba(0, 0, 0, 0.15);
 $shadow-color-hover: rgba(0, 0, 0, 0.25);
 
+$scrollbar-track-color: #f1f1f1; // Couleur de fond de la scrollbar (très clair)
+$scrollbar-thumb-color: #c1c1c1; // Couleur de la barre de défilement
+$scrollbar-thumb-hover-color: #a8a8a8; // Couleur au survol
 
 // Appliquer cette palette aux différents éléments

package/doc/automation-workflows.md

@@ -0,0 +1,102 @@
+# Automation with Workflows: Create Automated Processes
+
+The `data-primals-engine` features a powerful **Workflow** system that enables you to define and automate complex business processes. Workflows are sequences of steps and actions that can be triggered by various events or on a schedule, allowing for sophisticated automation directly within your backend.
+
+## Core Workflow Models
+
+The workflow system is composed of several interconnected data models:
+
+### 1. `workflow`
+
+The `workflow` model is the top-level definition of an automated process. It outlines the overall flow and its starting point.
+
+-   **`name`** (string, required): A unique, descriptive name for the workflow (e.g., "Order Validation", "Low Stock Notification").
+-   **`description`** (richtext, optional): A detailed explanation of the workflow's purpose.
+-   **`startStep`** (relation to `workflowStep`, optional): The first step to execute when the workflow is initiated.
+
+### 2. `workflowTrigger`
+
+A `workflowTrigger` defines an event or schedule that initiates a workflow.
+
+-   **`workflow`** (relation to `workflow`, required): The workflow that this trigger belongs to.
+-   **`name`** (string, required, unique): A descriptive name for the trigger (e.g., "New Order Created", "Stock < 5", "Monday 9 AM Report").
+-   **`type`** (enum, required): How the workflow is initiated:
+    -   `manual`: Triggered by a data event.
+    -   `scheduled`: Triggered by a cron schedule.
+-   **`onEvent`** (enum, for `manual` type): The data event that triggers the workflow: `DataAdded`, `DataEdited`, `DataDeleted`, `ModelAdded`, `ModelEdited`, `ModelDeleted`.
+-   **`targetModel`** (string, for `manual` type): The name of the model targeted by the `onEvent`.
+-   **`dataFilter`** (code - JSON, optional, for `manual` type): Optional MongoDB filter conditions checked against the `triggerData` before executing the workflow.
+-   **`cronExpression`** (string, for `scheduled` type): A cron expression (e.g., `'0 9 * * 1'` for Monday 9 AM) to schedule the workflow.
+-   **`isActive`** (boolean): Whether the trigger is currently active.
+-   **`env`** (code - JSON, optional): Environment variables (JSON key/value pairs) specific to this trigger.
+
+### 3. `workflowStep`
+
+A `workflowStep` represents a single stage within a workflow process. It can contain conditions, actions, and define the next steps based on success or failure.
+
+-   **`workflow`** (relation to `workflow`, required): The workflow this step belongs to.
+-   **`name`** (string, optional): A descriptive name for the step (e.g., "Check Inventory", "Send Confirmation Email").
+-   **`conditions`** (code - JSON, optional): Optional conditions (MongoDB filter syntax) that must be met before the step's actions are executed. These can reference `contextData`.
+-   **`actions`** (multiple relation to `workflowAction`, required): The main operations performed by this step.
+-   **`onSuccessStep`** (relation to `workflowStep`, optional): The next step to execute if this step's conditions are met and actions succeed.
+-   **`onFailureStep`** (relation to `workflowStep`, optional): The next step if conditions fail or any action within this step fails.
+-   **`isTerminal`** (boolean, default: `false`): Indicates if this step marks the end of a workflow path.
+
+### 4. `workflowAction`
+
+A `workflowAction` defines a specific operation to be performed by a `workflowStep`. This is where the actual work of the workflow happens.
+
+-   **`name`** (string, required): Name of the action (e.g., "Update Order Status", "Send Email", "Call Payment API").
+-   **`type`** (enum, required): The type of operation to perform:
+    -   `UpdateData`: Modify existing data in a `targetModel`.
+    -   `CreateData`: Add new data to a `targetModel`.
+    -   `DeleteData`: Remove data from a `targetModel`.
+    -   `ExecuteScript`: Run custom JavaScript code.
+    -   `HttpRequest`: Make an HTTP request to an external service.
+    -   `SendEmail`: Send an email.
+    -   `Wait`: Pause the workflow for a specified duration.
+    -   `GenerateAIContent`: Generate content using an AI model (e.g., OpenAI, Google Gemini).
+    -   `ExecuteServiceFunction`: Call a function from a registered internal service (e.g., 'stripe').
+-   **`targetModel`** (string, for data operations): The model to target.
+-   **`targetSelector`** (code - JSON, for `UpdateData`/`DeleteData`): Expression to filter the target document(s).
+-   **`fieldsToUpdate`** (code - JSON, for `UpdateData`): Key-value pairs of fields to update.
+-   **`dataToCreate`** (code - JSON, for `CreateData`): Object template for the new document.
+-   **`script`** (code - JavaScript, for `ExecuteScript`): The JavaScript code to execute.
+-   **`url`, `method`, `headers`, `body`** (for `HttpRequest`): Details for the HTTP request.
+-   **`emailRecipients`, `emailSubject`, `emailContent`** (for `SendEmail`): Email details.
+-   **`duration`, `durationUnit`** (for `Wait`): How long to pause.
+-   **`aiProvider`, `aiModel`, `prompt`** (for `GenerateAIContent`): AI model and prompt details.
+-   **`serviceName`, `functionName`, `args`** (for `ExecuteServiceFunction`): Service call details.
+
+## Workflow Execution (`workflowRun`)
+
+Each time a workflow is triggered, a `workflowRun` document is created to track its execution.
+
+-   **`workflow`** (relation to `workflow`): The workflow definition that was executed.
+-   **`contextData`** (code - JSON): A snapshot of the data or event that triggered this run, and any data generated during execution.
+-   **`status`** (enum): The current status (`pending`, `running`, `completed`, `failed`, `waiting`, `cancelled`).
+-   **`history`** (array of objects): Detailed execution history of each step and action.
+-   **`startedAt`, `completedAt`**: Timestamps for the run.
+-   **`error`**: Error message if the workflow run failed.
+
+## Example Workflow Scenario
+
+Consider a workflow to "Send a Welcome Email to New Users":
+
+1.  **`workflow`**: "New User Onboarding"
+2.  **`workflowTrigger`**:
+    -   `name`: "On New User Added"
+    -   `type`: `manual`
+    -   `onEvent`: `DataAdded`
+    -   `targetModel`: `user`
+3.  **`workflowStep`**: "Send Welcome Email"
+    -   `workflow`: "New User Onboarding"
+    -   `actions`: [ID of "Send Welcome Email Action"]
+    -   `onSuccessStep`: (optional) "Create Onboarding Task"
+4.  **`workflowAction`**: "Send Welcome Email Action"
+    -   `type`: `SendEmail`
+    -   `emailRecipients`: `{triggerData.contact.email}`
+    -   `emailSubject`: "Welcome to Our Platform, {triggerData.contact.firstName}!"
+    -   `emailContent`: "Hello {triggerData.contact.firstName}, welcome aboard..."
+
+This powerful system allows you to automate virtually any process, from simple notifications to complex data transformations and integrations with external services.

package/doc/core-concepts.md

@@ -0,0 +1,33 @@
+# Core Concepts: Data Modeling Fundamentals
+
+The `data-primals-engine` is built around a flexible and powerful data modeling system that allows you to define and manage your application's data structures without complex migrations. This section introduces the fundamental concepts of data modeling within the engine.
+
+## Dynamic and Schema-less Nature
+
+At its core, `data-primals-engine` leverages **MongoDB**, a NoSQL database. This provides inherent flexibility, allowing for a schema-less approach. You can define and update your data models either through a user interface or by providing JSON definitions, and the system adapts dynamically without requiring traditional database migrations. This significantly accelerates development and iteration cycles.
+
+## Models
+
+A **Model** is the blueprint for a collection of data. It defines the structure and characteristics of the documents you store. For example, a `User` model would define what properties a user object has (e.g., `username`, `email`, `roles`).
+
+Models are defined by a `name`, an optional `description`, an `icon`, and a list of `fields`. The engine comes with a set of default models for common entities like `user`, `product`, `workflow`, and more.
+
+## Fields
+
+**Fields** are the individual attributes that make up a model. Each field has a `name`, a `type`, and various optional properties that define its behavior and constraints.
+
+Common field types include:
+-   `string`: For text data.
+-   `number`: For numerical data.
+-   `boolean`: For true/false values.
+-   `datetime`: For date and time values.
+-   `relation`: To establish relationships between different models (e.g., a `product` model having a `category` field that relates to a `taxonomy` model).
+-   `enum`: For fields with a predefined set of allowed values.
+-   `file`: For handling file uploads (e.g., `profilePicture` in the `user` model).
+-   `code`: For storing code snippets (e.g., `script` in an `endpoint` model).
+
+Fields can also have properties like `required`, `unique`, `min`, `max`, `default` values, and `hint` for user guidance.
+
+This dynamic and field-based approach to data modeling provides the flexibility needed for rapidly building complex data-driven applications.
+
+**Next: Data Models**

package/doc/custom-api-endpoints.md

@@ -0,0 +1,40 @@
+# Custom API Endpoints: Create Dynamic HTTP Routes
+
+The `data-primals-engine` allows you to extend its API by defining **Custom API Endpoints**. These endpoints are dynamic HTTP routes that execute server-side JavaScript code directly from the backend, providing immense flexibility for custom logic and integrations.
+
+## The `endpoint` Model
+
+Custom API Endpoints are managed through the built-in `endpoint` data model. Each document in this model represents a unique API route.
+
+### Key Fields of the `endpoint` Model:
+
+-   **`name`** (string, required): A human-readable name for the endpoint.
+-   **`path`** (string, required, unique): The URL path segment that comes after `/api/actions/`. For example, if `path` is `send-welcome-email`, the full endpoint URL would be `/api/actions/send-welcome-email`.
+-   **`method`** (enum, required): The HTTP method (GET, POST, PUT, PATCH, DELETE) that this endpoint responds to.
+-   **`code`** (code, required): The JavaScript script that will be executed when this endpoint is called. This script has access to various utilities and the request context.
+-   **`isActive`** (boolean, default: `true`): If checked, the endpoint is active and can be called.
+-   **`isPublic`** (boolean, default: `false`): If checked, this endpoint will be accessible without authentication. Use with caution.
+
+### Script Execution Environment
+
+The JavaScript `code` field provides a powerful environment for your custom logic:
+
+-   **`db`**: An object providing methods for interacting with the database (e.g., `db.find`, `db.create`, `db.update`, `db.delete`).
+-   **`logger`**: A logging utility (e.g., `logger.info`, `logger.error`).
+-   **`env`**: Access to environment variables defined in the `env` model.
+-   **`request`**: The incoming HTTP request object, containing `body`, `query`, `params`, and `headers`.
+-   **`user`**: The authenticated user object (if `isPublic` is false).
+
+The script's return value will be sent as the JSON response to the client.
+
+### Example `endpoint` Definition (from `defaultModels.js`):
+
+```javascript
+// The default code for a new endpoint
+logger.info('Custom endpoint executed with body:', request.body);
+return { success: true, message: 'Endpoint executed!', received: request.body };
+```
+
+This feature allows developers to build highly customized backend logic directly within the `data-primals-engine`, making it a versatile tool for various application needs.
+
+**Next: Data Models**

package/doc/dashboards-kpis-charts.md

@@ -0,0 +1,49 @@
+# Dashboards, KPIs, and Charts: Track Your Key Metrics
+
+The `data-primals-engine` provides robust features for visualizing and tracking your application's performance and key metrics through customizable Dashboards and Key Performance Indicators (KPIs).
+
+## Dashboards
+
+A **Dashboard** serves as a personalized overview, allowing users to arrange and display various KPIs and charts relevant to their needs.
+
+### Key Fields of the `dashboard` Model:
+
+-   **`name`** (string, required): The customizable display name of the dashboard.
+-   **`description`** (string, optional): Provides additional context for the dashboard.
+-   **`layout`** (code - JSON, required): A JSON structure describing the organization of KPIs and charts. This defines how elements are arranged (e.g., in columns).
+    -   **Example Layout**: `"{ \"type\": \"columns\", \"columns\": [ [\"kpi_id_1\"], [\"kpi_id_2\", \"kpi_id_3\"] ] }"`
+-   **`settings`** (code - JSON, optional): JSON settings for the dashboard, such as a `defaultTimeRange` (e.g., 'last_7_days') or a `refreshInterval` in seconds.
+-   **`isDefault`** (boolean, default: `false`): If `true`, this dashboard is displayed by default for the user.
+
+## Key Performance Indicators (KPIs)
+
+**KPIs** are quantifiable measures used to evaluate the success of an organization, employee, etc., in meeting objectives. In `data-primals-engine`, KPIs are highly configurable to extract meaningful insights from your data.
+
+### Key Fields of the `kpi` Model:
+
+-   **`name`** (string, required): The display name of the KPI (e.g., "Total Revenue", "Active Users").
+-   **`description`** (string, optional): Additional information about the KPI.
+-   **`targetModel`** (string, required): The name of the data model on which to calculate the KPI (e.g., `order`, `user`).
+-   **`aggregationType`** (enum, required): The type of calculation to perform:
+    -   `count`: Count the number of documents.
+    -   `sum`: Sum a numeric field.
+    -   `avg`: Calculate the average of a numeric field.
+    -   `min`: Find the minimum value of a numeric field.
+    -   `max`: Find the maximum value of a numeric field.
+-   **`aggregationField`** (string, optional): The name of the numeric field to apply the aggregation to (e.g., `totalAmount`). Not required for `count` type.
+-   **`matchFormula`** (code - JSON, optional): A MongoDB `$match` JSON filter to apply before aggregation (e.g., `{ "status": "delivered" }`). This allows you to filter the data used for the KPI calculation.
+-   **`showTotal`** (boolean): Whether to display a grand total alongside the KPI.
+-   **`showPercentTotal`** (boolean): Whether to display the KPI value as a percentage of a total.
+-   **`totalMatchFormula`** (code - JSON, optional): A MongoDB `$match` JSON filter for calculating the total when `showPercentTotal` is enabled.
+-   **`unit`** (string, optional): The unit to display with the KPI value (e.g., "€", "$", "users").
+-   **`icon`** (string, optional): An icon name (e.g., `FaUsers`, `FaShoppingCart`) to visually represent the KPI.
+-   **`order`** (number, optional): The display order of the KPI on a dashboard.
+-   **`color`** (string, optional): A color associated with the KPI for visual distinction.
+
+## Charts
+
+While the `kpi` model focuses on single aggregated values, the engine also supports the integration of charts to visualize data trends and distributions over time or across categories. These are typically rendered based on underlying KPI data or direct queries, offering a richer analytical experience.
+
+By combining Dashboards, configurable KPIs, and charting capabilities, `data-primals-engine` empowers users to effectively monitor and understand their key business metrics.
+
+**Next: Users**