data-primals-engine 1.7.2 → 1.7.3

package/doc/automation-workflows.md

@@ -1,102 +1,141 @@
-# 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.
+# 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:
+
+| Action Type                | Description                                                              | Related Properties                                                                                             |
+ |:---------------------------|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+| **`UpdateData`**             | Modify existing data in a `targetModel`.                                 | - **`targetModel`**: The model to target. Ex: `'product'`<br/>- **`targetSelector`**: Expression to filter the target document(s). Ex: `{ "_id": "{triggerData._id}" }`<br/>- **`fieldsToUpdate`**: Key-value pairs of fields to update. Ex: `{ "status": "shipped", "shippedAt": "{now}" }` |
+| **`CreateData`**             | Add new data to a `targetModel`.                                         | - **`targetModel`**: The model to target. Ex: `'product'`<br/>- **`dataToCreate`**: Object template for the new document. Ex: `{ "title": "New Task for {triggerData.name}", "status": "todo" }` |
+| **`DeleteData`**             | Remove data from a `targetModel`.                                        | - **`targetModel`**: The model to target. Ex: `'product'`<br/>- **`targetSelector`**: Expression to filter the target document(s). Ex: `{ "_id": "{triggerData._id}" }` |
+| **`ExecuteScript`**          | Run custom JavaScript code in a secure sandbox.                          | - **`script`**: The JavaScript code to execute. Ex: `return { newPrice: context.triggerData.price * 1.1 };` |
+| **`HttpRequest`**            | Make an HTTP request to an external service.                             | - **`url`**: The URL for the HTTP request. Ex: `'https://api.example.com/orders/{triggerData.orderId}'`<br/>- **`method`**: The HTTP method. Ex: `'POST'`<br/>- **`headers`**: The HTTP headers. Ex: `{ "Authorization": "Bearer {env.API_KEY}" }`<br/>- **`body`**: The request body. Ex: `{ "status": "completed" }` |
+| **`SendEmail`**              | Send an email using the configured SMTP settings.                        | - **`emailRecipients`**: List of email recipients. Ex: `['{triggerData.customer.email}']`<br/>- **`emailSubject`**: The email subject. Ex: `'Order Confirmation #{triggerData.orderId}'`<br/>- **`emailContent`**: The email body (HTML). Ex: `'<h1>Thank you!</h1>'` |
+| **`Wait`**                   | Pause the workflow for a specified duration.                             | - **`duration`**: How long to pause. Ex: `10`<br/>- **`durationUnit`**: The unit for the duration. Ex: `'minutes'` |
+| **`GenerateAIContent`**      | Generate content using an AI model (e.g., OpenAI, Google Gemini).        | - **`aiProvider`**: The AI provider. Ex: `'OpenAI'`<br/>- **`aiModel`**: The specific model to use. Ex: `'gpt-4o-mini'`<br/>- **`prompt`**: The prompt to send to the AI. Ex: `'Summarize: {triggerData.description}'` |
+| **`ExecuteServiceFunction`** | Call a function from a registered internal service (e.g., 'stripe').     | - **`serviceName`**: The name of the service. Ex: `'stripe'`<br/>- **`functionName`**: The function to call. Ex: `'createRefund'`<br/>- **`args`**: Arguments for the function. Ex: `['{triggerData.chargeId}', 5000]` |
+
+## 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.
+
+## Creating a Workflow Programmatically: A Step-by-Step Example
+
+Let's build a complete workflow that sends a welcome email to every new user who signs up. This entire process can be automated by creating the necessary workflow documents via API calls using `insertData`.
+
+### 1. The `workflow`
+
+First, we define the main workflow document. This acts as a container for the steps and logic. We link it to its starting step by name.
+
+```javascript
+await insertData("workflow", {
+    "name": "New User Onboarding",
+    "description": "Sends a welcome email to new users upon registration.",
+    "startStep": { "$find": { "name": "Send Welcome Email" } } // Link to the first step
+});
+```
+
+### 2. The `workflowAction`
+
+Next, we define the specific task to be performed: sending the email. The `emailRecipients`, `emailSubject`, and `emailContent` fields use placeholders like `{triggerData.contact.email}`. These will be automatically replaced with the data from the user document that triggered the workflow.
+
+```javascript
+await insertData("workflowAction", {
+    "name": "Send Welcome Email Action",
+    "type": "SendEmail",
+    "emailRecipients": "{triggerData.contact.email}",
+    "emailSubject": "Welcome to Our Platform, {triggerData.contact.firstName}!",
+    "emailContent": "<h1>Welcome aboard, {triggerData.contact.firstName}!</h1><p>We're thrilled to have you join our community.</p>"
+});
+```
+> **Note**: For this to work, your SMTP settings must be configured either in your `.env` file or in the `env` model for the user running the workflow.
+
+### 3. The `workflowStep`
+
+Now, we create a step that executes our action. A workflow can have multiple steps, but for this simple case, we only need one. We link the step to the workflow and the action by their names.
+
+```javascript
+await insertData("workflowStep", {
+  "name": "Send Welcome Email",
+  "workflow": { "$find": { "name": "New User Onboarding" } },
+  "actions": [
+    { "$find": { "name": "Send Welcome Email Action" } }
+  ],
+  "isTerminal": true // This is the last step in this path.
+});
+```
+
+### 4. The `workflowTrigger`
+
+Finally, we define what will start the workflow. This trigger will listen for new documents being added (`DataAdded`) to the `user` model.
+
+```javascript
+await insertData("workflowTrigger", {
+  "name": "On New User Registration",
+  "workflow": { "$find": { "name": "New User Onboarding" } },
+  "type": "manual",
+  "onEvent": "DataAdded",
+  "targetModel": "user",
+  "isActive": true
+});
+```
+
+With these four API calls, your automated welcome email system is now active. Any new user created in the system will automatically receive a personalized welcome email.
+
+This powerful system allows you to automate virtually any process, from simple notifications to complex data transformations and integrations with external services.
+
+
+**[Next: Data Packs](packs-gallery)**

package/doc/dashboards-kpis-charts.md

@@ -1,49 +1,47 @@
-# 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**
+# 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.
+
+### The `dashboard` Model
+
+| Attribute         | Type                      | Description                                                                                                                                      |
+|:------------------|:--------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`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. Defines how elements are arranged (e.g., in columns).<br/>*Example: `"{ \"type\": \"columns\", \"columns\": [ [\"kpi_id_1\"], [\"kpi_id_2\"] ] }"`* |
+| **`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, optional         | 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.
+
+### The `kpi` Model
+
+| Attribute              | Type                      | Description                                                                                                                                      |
+|:-----------------------|:--------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`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`, `sum`, `avg`, `min`, or `max`.                                                                      |
+| **`aggregationField`**   | string, optional          | The name of the numeric field to aggregate (e.g., `totalAmount`). Not required for `count`.                                                      |
+| **`matchFormula`**       | code (JSON), optional     | A MongoDB `$match` filter to apply before aggregation (e.g., `{ "status": "delivered" }`).                                                       |
+| **`showTotal`**          | boolean, optional         | If `true`, displays a grand total alongside the KPI.                                                                                             |
+| **`showPercentTotal`**   | boolean, optional         | If `true`, displays the KPI value as a percentage of a total.                                                                                    |
+| **`totalMatchFormula`**  | code (JSON), optional     | A MongoDB `$match` 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](users)**