data-primals-engine 1.7.1 → 1.7.3

package/doc/AI-assistance.md

@@ -1,93 +1,117 @@
 # AI Assistance: Leverage Artificial Intelligence
 
-`data-primals-engine` includes a powerful, built-in AI assistant named **Prior**. This assistant is designed to understand natural language queries, allowing you to interact with your data, generate insights, and perform actions without writing complex code or API requests.
+The `data-primals-engine` integrates powerful generative AI capabilities directly into its core, allowing you to automate content creation, analyze data, and enrich your business processes.
 
 ## Enabling the AI Assistant
 
-To use the AI assistant, you must first provide API keys for one or more supported AI providers. The engine natively supports providers like **OpenAI, Google (Gemini), DeepSeek, and Anthropic**.
+To use the AI features, you must first provide API keys for one or more supported AI providers. The engine natively supports providers like **OpenAI, Google (Gemini), DeepSeek, and Anthropic**.
 
 You can configure your keys in two ways:
 
 1.  **Environment Variables**: Set the appropriate variable in your `.env` file. This is the recommended approach for production.
-    ```env
-    # Choose one or more providers
-    OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
-    GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxx
-    DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
-    ```
 
-2.  **`env` Model**: For user-specific keys, you can store them in the `env` model within the application. The assistant will automatically look for a key belonging to the current user.
-
-Once a key is configured, the AI assistant chat interface becomes available in the UI.
-
-## Core Capabilities
-
-The assistant, "Prior," can perform a wide range of actions based on your natural language commands.
-
-### 1. Data Querying and Visualization
-
-You can ask the assistant to find, filter, and display your data. It can present the results in various formats.
-
--   **Simple Search**:
-    > "Show me the latest 5 orders from French customers."
-
--   **Chart Generation**: Create charts on the fly.
-    > "Create a bar chart of user sign-ups per month for the last year."
-
--   **Custom HTML Views**: Generate sophisticated, styled views of your data using Handlebars templates.
-    > "Build a dashboard of my active projects with their status and due dates, using a modern dark theme."
-
-### 2. Data Modification (with Confirmation)
+```env
+# Choose one or more providers
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
+GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxx
+DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
+ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
+```
 
-The assistant can create, update, or delete data, but it will **always ask for your confirmation** before executing a modifying action. This provides a critical safety layer.
+2.  **`env` Model**: For user-specific keys, you can store them in the `env` model within the application. The assistant will automatically look for a key belonging to the current user.
 
--   **Create Data**:
-    > "Create a new task to 'Follow up with Client X' due tomorrow."
+Once a key is configured, AI capabilities become available, most notably within the automation engine.
 
--   **Update Data**:
-    > "Update the status of all tickets in the 'Support' category to 'resolved'."
+## AI in Workflows: The `GenerateAIContent` Action
 
--   **Delete Data**:
-    > "Delete all draft products created before last month."
+The most powerful way to use AI in `data-primals-engine` is by integrating it into your **Workflows**. The `GenerateAIContent` action type allows you to call an AI model as a step in any automated process.
 
-When you issue such a command, the assistant will respond with a summary of the action it intends to perform and a "Confirm" button. The action is only executed after you click it.
+This is perfect for tasks like:
+-   Summarizing a new support ticket.
+-   Generating a product description when a new product is added.
+-   Classifying incoming data based on its content.
+-   Translating text.
 
-### 3. Answering Questions
+### Example: Automatically Generating a Product Description
 
-The assistant can answer questions about the data it has access to.
+Let's create a complete workflow that automatically generates an SEO description whenever a new product is added without one.
 
-> "What was our total revenue in the last quarter?"
+This workflow can be created programmatically by making the following API calls from your JavaScript code.
 
-## How It Works: The Reasoning Loop
 
-When you send a message, the assistant follows a strict reasoning process:
+#### 1. The `workflow`
 
-1.  **Analyze Intent**: It first analyzes your request to understand what you want to do.
-2.  **Search Models (Internal Step)**: Its first action is always to call the `search_models` tool internally. This gives it the exact structure, field names, and types for the relevant data models. This step is crucial for preventing errors and "hallucinations."
-3.  **Formulate Action**: Based on your intent and the model structures it found, it formulates a final action, such as `search`, `generateChart`, or a `post` request.
-4.  **Execute or Confirm**:
-    -   If it's a read-only action (like `search` or `generateChart`), it executes it and displays the result.
-    -   If it's a write action (like `post` or `delete`), it presents the action to you for confirmation.
+First, we define the main workflow. This document acts as a container for the steps and logic.
 
-## AI in Workflows: The `GenerateAIContent` Action
+```javascript
+await insertData("workflow", {
+    "name": "Generate Product SEO Description",
+    "description": "When a new product is created without an SEO description, this workflow uses AI to generate one based on the product's name.",
+    "startStep": { "$find": { "name": "Generate and Update Description" } }
+});
+```
 
-Beyond the chat interface, you can leverage AI directly within your automation **Workflows**. The `GenerateAIContent` action allows you to call an AI model as a step in a workflow.
+#### 2. The `workflowAction` documents
 
-This is perfect for tasks like:
--   Summarizing a new support ticket.
--   Generating a product description when a new product is added.
--   Classifying incoming data based on its content.
--   Translating text.
+Next, we define the individual actions that will be performed. We need two actions: one to generate the content with AI, and another to update the product with that content. We use `insertData` to create both in a single call.
 
-**Example `workflowAction`:**
-```json
-{
-    "name": "Summarize Ticket",
+```javascript
+await insertData("workflowAction", [
+  {
+    "name": "Generate SEO Content",
     "type": "GenerateAIContent",
     "aiProvider": "OpenAI",
-    "aiModel": "gpt-4-turbo",
-    "prompt": "Summarize the following support ticket in one sentence: {triggerData.description}"
-}
+    "aiModel": "gpt-4o-mini",
+    "prompt": "Write a short, engaging, and SEO-optimized product description (30-40 words) for the following product: '{triggerData.name}'. Return only the description text, without any introductory or concluding phrases."
+  },
+  {
+    "name": "Update Product with AI Content",
+    "type": "UpdateData",
+    "targetModel": "product",
+    "targetSelector": { "_id": "{triggerData._id}" },
+    "fieldsToUpdate": { "seoDescription": "{context.aiContent}" }
+  }
+]);
+```
+> **Note**: The `targetSelector` and `fieldsToUpdate` use placeholders. `{triggerData._id}` refers to the ID of the product that started the workflow, and `{context.aiContent}` refers to the text generated by the previous AI action.
+
+#### 3. The `workflowStep`
+
+Now, we create a step that groups our actions together. A workflow can have multiple steps that execute in sequence. For this simple case, we only need one, which we create with `insertData`.
+
+```javascript
+await insertData("workflowStep", {
+  "name": "Generate and Update Description",
+  "workflow": { "$find": { "name": "Generate Product SEO Description" } },
+  "actions": [
+    { "$find": { "name": "Generate SEO Content" } },
+    { "$find": { "name": "Update Product with AI Content" } }
+  ],
+  "isTerminal": true
+});
 ```
 
+#### 4. The `workflowTrigger`
+
+Finally, we define the trigger that will start the workflow. This trigger will listen for new documents being added (`DataAdded`) to the `product` model. It also includes a `dataFilter` to ensure it only runs if the `seoDescription` field is empty. We create it with `insertData`.
+
+```javascript
+await insertData("workflowTrigger", {
+  "name": "On New Product Added without SEO Description",
+  "workflow": { "$find": { "name": "Generate Product SEO Description" } },
+  "type": "manual",
+  "onEvent": "DataAdded",
+  "targetModel": "product",
+  "dataFilter": {
+    "$or": [
+      { "seoDescription": { "$exists": false } },
+      { "seoDescription": "" }
+    ]
+  },
+  "isActive": true
+});
+```
+
+With these four API calls, your automated AI content generation workflow is now active. Any new product created without an SEO description will automatically have one generated and saved.
+
 This integration of AI both as an interactive assistant and as an automation component makes `data-primals-engine` a powerful platform for building intelligent applications.

package/doc/Concepts.md

@@ -0,0 +1,122 @@
+# Fundamental Concepts
+
+`data-primals-engine` is built on a set of core concepts designed to provide maximum flexibility and power. Understanding these concepts is essential to getting the most out of the platform.
+
+---
+
+## 1. [Models](data-models)
+
+A **model** represents a data entity in your application, similar to a table in an SQL database or a collection in MongoDB. Each model has a set of fields that define the structure of the data it contains.
+
+- **Visual Definition**: Models can be created and modified directly from the user interface, without requiring manual database migrations.
+
+- **Flexibility**: A model's structure can be updated at any time.
+### Model Generation
+Models are the way to handle structured data. They organize data and they can be declared in JSON.
+
+```json
+{
+  "name": "product",
+  "description": "E-commerce product schema",
+  "fields": [
+    { "name": "name", "type": "string", "required": true },
+    { "name": "price", "type": "number", "required": true },
+    { "name": "stock", "type": "number", "default": 0 },
+    { "name": "category", "type": "relation", "relation": "taxonomy",
+       "relationFilter": { "$eq": ["$type", "category"] }
+    },
+    { "name": "tags", "type": "relation", "relation": "taxonomy", "multiple": true,
+       "relationFilter": { "$eq": ["$type", "keyword"] }
+    }
+  ]
+}
+```
+
+#### Dynamic Index Management
+
+The engine features a sophisticated system for managing database indexes directly from the model editor UI. This eliminates the need for manual database administration or migration scripts for indexing, significantly speeding up development and reducing errors.
+
+Indexes are created, updated, and removed automatically when you save a model's structure. All created indexes are **partial indexes**, meaning they only include documents for the specific model and user, which optimizes storage and performance.
+
+You can enable indexing on any field by checking the `index` box in the model editor and choosing one of the following types:
+
+| Index Type      | `indexType` | Use Case & Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         -|
+ |-----------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+| **Regular**     | `regular`   | **Purpose**: The standard index for most use cases. It dramatically speeds up queries, sorting, and filtering on a specific field. <br/> **Behavior**: Creates a standard ascending B-tree index on a single field. This is the default and most common index type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -|
+| **Text Search** | `text`      | **Purpose**: Enables powerful, language-aware full-text search across one or more fields. It's ideal for implementing search bars that need to query descriptions, titles, and other text-heavy content. <br/> **Behavior**: Creates a single, special **compound `text` index** for the entire model. All fields marked with `indexType: 'text'` are included in this single index. This allows you to use MongoDB's `$text` operator in your search queries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -|
+| **Geospatial**  | `2dsphere`  | **Purpose**: Essential for location-based queries. It allows you to efficiently find documents within a certain radius, within a polygon, or sorted by distance. <br/> **Behavior**: Creates a `2dsphere` index on a single field. This index type should be used exclusively on fields of type `geolocation` which store data in GeoJSON format (e.g., `{ "type": "Point", "coordinates": [ -73.97, 40.77 ] }`). |
+
+### Model constraints
+```javascript
+{
+    "name": "modelName",
+    "fields": [
+         { "name": "fieldName1", .... },
+         { "name": "fieldName2", .... }
+    ],
+    "constraints": [
+        // uniqueness
+        { "name": "uniqueConstraint", type: "unique", keys: ["fieldName1", "fieldName2"] }
+    ]
+}
+```
+### Other model features
+- Handles up to 1500 direct relations per document by default (can be customized). For larger datasets, use intermediate collections or maxRelationsPerData constant.
+- Anonymizable fields (encrypted for API users)
+
+
+## 2. [Fields](data-models)
+
+**Fields** are the attributes that make up a model. `data-primals-engine` supports a wide variety of field types to cover all needs:
+
+### Fields types
+
+| Type        | Description                                                                         | 	Properties/Notes                                                         | 
+|:------------|:------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
+| string	     | Character string.                                                                   | 	minLength, maxLength                                                     |
+| string_t	   | International character string ID.                                                  | 	same as string, translated in { key, value }                             |
+| number	     | Numeric value (integer or float).                                                   | 	min, max                                                                 |
+| boolean	    | Boolean value (true/false).	                                                        | –                                                                         |
+| date	       | Stores a ISO date.	                                                                 | –                                                                         |
+| datetime	   | Stores an ISO date and time.	                                                       | –                                                                         |
+| richtext	   | Rich text field (HTML) for WYSIWYG editors.	                                        |                                                                           |
+| richtext_t	 | International rich text field (HTML) for WYSIWYG editors.	                          | i18n                                                                      |
+| email	      | String validated as an email address.	                                              | –                                                                         |
+| password	   | String that will be automatically hashed.	                                          | –                                                                         |
+| enum	       | Allows selecting a value from a predefined list.	                                   | items: ["value1", "value2"]                                               |
+| relation	   | Creates a link to a document in another model.                                      | 	relation: "target_model_name", multiple: true/false                      |
+| file	       | For uploading a file (stored on S3 if configured).	                                 | allowedTypes:['image/jpeg', 'image/png', 'image/bmp'], maxSize: 1024*1000 |
+| image	      | Specialized file type for images, with preview.	                                    | –                                                                         |
+| array	      | Stores a list of values.	                                                           | itemsType: 'enum' // any type except relations                            |
+| object	     | Stores a nested JSON object.	–                                                      |                                                                           |
+| code	       | Stores language="*" as string, stores language="json" as arbitrary JSON structure.	 | language="json" conditionBuilder=true                                     |                                            
+| color	      | Stores an hexadecimal value of an RGB color	                                        | '#FF0000'                                                                 |                                            
+| model	      | Stores a model by name                                                              | –                                                                         |                                            
+| modelField	 | Stores a model field path	                                                          | –                                                                         |                                            
+
+
+Each field can have specific validation rules to guarantee data integrity.
+
+## 3. [Permissions (RBAC)](roles-permissions)
+
+Access management is handled by a **Role-Based Access Control (RBAC)** system.
+
+- **Roles**: You can define roles (e.g., `Admin`, `Editor`, `Visitor`).
+
+- **Granular Permissions**: For each model, you can assign CRUD (Create, Read, Update, Delete) permissions to each role. For example, an `Editor` can create and modify articles, but not delete them.
+
+This system allows for granular security of access to your data.
+
+## 4. [User management](users)
+
+The engine includes a robust authentication system based on **JWT (JSON Web Tokens)**.
+
+- ****: A `User` model is typically used to manage user accounts.
+
+- **Security**: `JWT_SECRET` ensures that tokens cannot be forged.
+
+## 5. Advanced Data Management
+
+- **Complex Queries**: Leverage the power of MongoDB to perform complex queries and aggregations on your data.
+
+- **Automatic Auditing**: The engine can automatically maintain a history of changes for each record, allowing you to know who did what and when.

package/doc/Custom-Endpoints.md

@@ -0,0 +1,31 @@
+# Custom API Endpoints
+
+While `data-primals-engine` provides a full REST API for CRUD operations on your models, you may sometimes need to create API endpoints with specific business logic.
+
+Custom API endpoints allow you to extend the engine's native API in a secure and controlled manner.
+
+---
+
+## Why Create a Custom API Endpoint?
+
+- To execute complex logic that goes beyond simple CRUD operations (e.g., `POST /api/orders/{id}/processPayment`).
+
+- To aggregate data from multiple models into a single response.
+
+- To integrate with external services.
+
+## Creation and Configuration
+
+Custom API endpoints can be created directly from the administration interface. During creation, you configure the following:
+
+- **HTTP Route**: The URL path (e.g., `/my-custom-action`).
+
+- **HTTP Method**: `GET`, `POST`, `PUT`, `DELETE`, etc.
+
+- **Permissions**: Which role is authorized to call this API point.
+
+- **Execution Code**: You write your logic in **JavaScript (Node.js)** directly in a secure (sandbox) environment.
+
+## Secure Execution Environment
+
+The code you write for a custom API point runs in an isolated environment. You have controlled access to engine features (such as `searchData`, `insertData`) and certain Node.js libraries, which ensures that your custom code cannot compromise the security or stability of the main application.

package/doc/Event-system.md

@@ -63,17 +63,16 @@ When multiple listeners are registered for an event, their return values are mer
 
 Here is a list of the most important events you can listen to:
 
-| Event              | Description                                                      | Scope  | Triggered by                 | Arguments (Payload)                                                                |
-|:-------------------|:-----------------------------------------------------------------|:-------|:-----------------------------|:-----------------------------------------------------------------------------------|
-| `OnServerStart`    | Triggered once the HTTP server is started and listening.         | System | `engine.start()`             | `engine`                                                                           |
-| `OnDatabaseLoaded` | Triggered once the lient is ready                                | System |                              | `engine`                                                                           |
-| `OnModelsLoaded`   | Triggered after the initial models are loaded at startup.        | System | `setupInitialModels()`       | `engine`, `dbModels`                                                               |
-| `OnModelEdited`    | Triggered after a model definition has been modified.            | System | `editModel()`                | `newModel`                                                                         |
-| `OnDataAdded`      | Triggered after new data has been inserted.                      | System | `insertData()`               | `engine`, `insertedDocs`                                                           |
-| `OnDataEdited`     | Triggered after data has been edited.                            | System | `editData()` / `patchData()` | `engine`, `{modelName, before, after}`                                             |
-| `OnDataDeleted`    | Triggered just after data is actually deleted.                   | System | `deleteData()`               | `engine`, `{model, filter}`                                                        |
-| `OnDataSearched`   | Triggered after a data search.                                   | System | `searchData()`               | `engine`, `{data, count}`                                                          |
-| `OnDataInsert`     | Triggered just before data insertion. Allows modifying the data. | System | internal                     | `data`                                                                             |
-| `OnDataValidate`   | Triggered to override validation checks.                         | System | internal                     | `value`, `field`, `data`                                                           |
-| `OnChatAction`     | Triggered when an AI assistant decides on an action.             | User   | `handleChatRequest`          | `action`, `params`, `parsedResponse`, `command`, `llmOptions`, `user`, `reqParams` |
-| `OnSystemPrompt`   | Triggered to override the AI assistant's system prompt.          | User   | `handleChatRequest`          | `user`                                                                             |
+| Event            | Description                                                             | Scope  | Triggered by             | Arguments (Payload)                                                  |
+|:-----------------|:------------------------------------------------------------------------|:-------|:-------------------------|:---------------------------------------------------------------------|
+| `OnServerStart`    | Triggered once the HTTP server is started and listening.                | System | `engine.start()`           | `engine`                                                               |
+| `OnModelsLoaded`   | Triggered after the initial models are loaded at startup.               | System | `setupInitialModels()`     | `engine`, `dbModels`                                                     |
+| `OnModelEdited`    | Triggered after a model definition has been modified.                   | System | `editModel()`              | `newModel`                                                             |
+| `OnDataAdded`      | Triggered after new data has been inserted.                             | System | `insertData()`             | `engine`, `insertedDocs`                                                 |
+| `OnDataEdited`     | Triggered after data has been edited.                                   | System | `editData()` / `patchData()` | `engine`, `{modelName, before, after}`                                   |
+| `OnDataDeleted`    | Triggered just after data is actually deleted.                          | System | `deleteData()`             | `engine`, `{model, filter}`                                              |
+| `OnDataSearched`   | Triggered after a data search.                                          | System | `searchData()`             | `engine`, `{data, count}`                                                |
+| `OnDataInsert`     | Triggered just before data insertion. Allows modifying the data.        | System | internal                 | `data`                                                                 |
+| `OnDataValidate`   | Triggered to override validation checks.                                | System | internal                 | `value`, `field`, `data`                                                   |
+| `OnChatAction`     | Triggered when an AI assistant decides on an action.                    | User   | `handleChatRequest`        | `action`, `params`, `parsedResponse`, `command`, `llmOptions`, `user`, `reqParams` |
+| `OnSystemPrompt`   | Triggered to override the AI assistant's system prompt.                 | User   | `handleChatRequest`        | `user`                                                                 |

package/doc/Home.md

@@ -0,0 +1,33 @@
+# Welcome to the data-primals-engine Wiki! 👋
+
+This wiki is your central guide to using, integrating, and extending the platform.
+
+## 🧭 Explore the Platform
+Discover the core features to get started building and managing your data.
+Link to the official documentation: https://data.primals.net/en/documentation/
+
+- 🧠 [Core Concepts](Concepts): Explore the fundamentals of data modeling.
+- 🔌 [Custom API Endpoints](custom-api-endpoints): Create dynamic HTTP routes directly from the backend.
+- 🏗️ [Data Models](data-models): Structure your information.
+- 🗃️ [Data Management](data-management): Create, read, update, and delete your entries.
+- 📈 [Dashboards, KPIs, and Charts](dashboards-kpis-charts): Track your key metrics.
+- 👥 [Users](users): Manage access to the platform.
+- 🔐 [Roles and Permissions](roles-permissions): Define who can see and do what.
+- ⚙️ [Automation with Workflows](automation-workflows): Create automated processes.
+- 🎁 [Pack Gallery](Packs-gallery): Discover ready-to-use configurations.
+- 🤖 [AI Assistance](AI-assistance): Leverage artificial intelligence.
+
+## 🧩 Extend Capabilities
+Go further by developing your own features and business logic.
+
+- ⚡ [Event System](Event-system): React to events in real time.
+- 🧠 [Advanced Workflows](Advanced-workflows): Create complex logic with custom scripts.
+- 📦 [Modules](Modules): Package and share your developments.
+- 🚀 [Sharding & Replication](sharding-replication): Scale horizontally and ensure high availability.
+- ❤️ [Contribute to the project (CONTRIBUTING.md)](https://github.com/anonympins/data-primals-engine/blob/main/CONTRIBUTING.md): Join the developer community.
+
+## 💻 For Developers
+Essential tools for a seamless development experience.
+
+- 📖 [Explore the API with Swagger](https://data.primals.net/api-docs/): Test API access points directly from your browser.
+- 📮 [Postman Collection](https://data.primals.net/doc/API.postman_collection.json): Import our collection to start querying in just a few clicks.

package/doc/Modules.md

@@ -0,0 +1,83 @@
+# Modules: Packaging and Extending Features
+
+The `data-primals-engine` is designed to be modular, allowing you to enable, disable, or create new features in a clean and organized way. A **Module** is a self-contained unit of functionality that plugs into the core engine at startup.
+
+This approach keeps the core lightweight while allowing for powerful extensions like SSO authentication, payment gateway integrations, or custom API functionalities.
+
+## How Modules Work
+
+1.  **Discovery**: The engine looks for modules in the `src/modules/` directory.
+2.  **Activation**: You specify which modules to activate using the `Config` object.
+3.  **Initialization**: For each active module, the engine calls its exported `onInit(engine)` function, passing the main engine instance. This is the module's entry point to interact with the system.
+
+## Enabling an Existing Module
+
+The engine comes with several built-in modules, such as authentication providers. To enable one, you add its name to the `modules` array in your configuration **before** initializing the engine.
+
+**Example: Enabling Google SSO and the Assistant**
+
+```javascript
+import { Engine, Config } from 'data-primals-engine';
+
+// Add modules to the list of modules to be loaded
+Config.Set("modules", ["auth-google", "assistant"]);
+
+const app = express();
+const engine = await Engine.Create({ app });
+```
+
+You may also need to install peer dependencies (`npm install passport-google-oauth20`) and set environment variables (`GOOGLE_CLIENT_ID`, etc.) as required by the module.
+
+## Creating a New Module
+
+Creating a module is straightforward. It only requires a JavaScript file in the `src/modules/my-module/` directory that exports an `async` function named `onInit`.
+
+### Step 1: Create the Module File
+
+Create a new file, for example: `src/modules/greeter/greeter.js`
+
+### Step 2: Write the `onInit` Function
+
+In `greeter.js`, write your initialization logic. The `onInit` function gives you access to the entire engine.
+
+```javascript
+// src/modules/greeter/greeter.js
+
+export async function onInit(engine) {
+    // 1. Get components from the engine
+    const logger = engine.getComponent('Logger');
+    const Event = engine.getComponent('Event');
+
+    // 2. Register a new API endpoint
+    engine.get('/api/greet/:name', (req, res) => {
+        const { name } = req.params;
+        res.json({ message: `Hello, ${name}! Welcome to our custom module.` });
+    });
+
+    // 3. Listen to a core event
+    Event.Listen('OnDataAdded', (engine, insertedDocs) => {
+        if (insertedDocs?.[0]._model === 'user') {
+            logger.info(`A new user has signed up: ${insertedDocs[0].username}`);
+        }
+    }, 'event', 'system');
+
+    // 4. Log that the module has been loaded
+    logger.info("Module 'greeter' loaded successfully.");
+}
+```
+
+### Step 3: Enable Your New Module
+
+In your main server file, enable your module via the `Config` object.
+
+```javascript
+Config.Set("modules", ["greeter"]); // Add your module's folder name
+
+const engine = await Engine.Create({ app });
+// When the server starts, you will see "Module 'greeter' loaded successfully." in your logs.
+// You can now access http://localhost:7633/api/greet/World
+```
+
+Modules are the preferred way to build reusable and maintainable extensions for `data-primals-engine`.
+
+**[Next: Sharding / Replication](sharding-replication)**