# Welcome!

Welcome to the AI platform that puts the power of innovation in your hands.

Madrix is a platform for **designing, generating and operating** corporate apps with AI.

You describe what you want.\
Agents execute deterministic tools.\
You review, approve and publish.

### What you can build

Use Madrix to create:

* CRMs, helpdesks and backoffices.
* Internal portals and operational flows.
* Apps with business rules, permissions and environments (Dev/Staging/Prod).

{% hint style="info" %}
Here “agentic AI” means: the AI **not only writes text**. It **executes actions** via tools, with traceability and approval checkpoints.
{% endhint %}

### Get started now (15 min)

Follow the onboarding and have your first app running:

* [Start here](/get-started-here)

If you prefer to start with ready-made examples:

* [Prompt Templates](/hands-on-tutorials/4.-prompt-templates)

Then, deepen with:

* [Hands-on Tutorials](/hands-on-tutorials)
* [Demonstrations](/demonstrations)

### How to navigate the documentation

Choose a path and follow the links:

{% tabs %}
{% tab title="Build fast" %}

* Complete onboarding: [Start here](/get-started-here)
* Ready prompts: [Prompt Templates](/hands-on-tutorials/4.-prompt-templates)
* Guided examples: [Demonstrations](/demonstrations)
  {% endtab %}

{% tab title="Product / Platform" %}

* Overview of the blocks: [Platform](/documentation/platform)
* AI Features: [AI and Agentic Coding](/documentation/chat-ai-mode)
* Deepen by topic: [Hands-on Tutorials](/hands-on-tutorials)
  {% endtab %}

{% tab title="IT / Integrations / Ops" %}

* Connect with your stack: [Integrations and API](/documentation/integrations-and-api)
* Governance and security: [Security and Compliance (IT)](/documentation/runtime-settings)
* Deployment and operation: [Deployment and Ops](broken://spaces/jLpkUQEEJ5BcMqj70lza/pages/dc39c25885b9d5f0fe5c3e1f1f6f2e7bd95aec9f)
  {% endtab %}

{% tab title="Troubleshooting" %}

* When stuck: [Troubleshooting](/troubleshooting)
  {% endtab %}
  {% endtabs %}

### How it works (quick view)

1. **Prompt** with objective, modules, entities and rules.
2. **Specification** to review and approve.
3. **Generation** of backend, UI and integrations.
4. **Preview** to test the app.
5. **Deploy** to environments (Dev/Staging/Prod).

### Concepts (in 2 minutes)

* **Project**: the “container” of your app.
* **Environment**: where the app runs (Dev/Staging/Prod).
* **Module**: a functional domain (e.g.: Tasks, Customers).
* **Entity**: the main data of the domain (e.g.: Task, Customer).
* **Business rule**: validations and automations of the process.
* **Roles and permissions (RBAC)**: who can see and do what.

### What to expect

1. **Ease of use**
   * Guided interface.
   * Clear flow from prompt → approval → execution.
2. **Flexibility**
   * Models and rules adapted to your business.
   * Iterative evolution with Chat AI and Editor.
3. **Efficiency**
   * Less time between idea and running app.
   * Less rework with approved specification.
4. **Collaboration**
   * Teams work on the same project.
   * Roles and permissions for governance.

### Next steps

* Understand the main blocks: [Platform](/documentation/platform)
* Explore AI features: [AI and Agentic Coding](/documentation/chat-ai-mode)
* Connect with your stack: [Integrations and API](/documentation/integrations-and-api)
* Grab ready-made prompts: [Prompt Templates](/hands-on-tutorials/4.-prompt-templates)
* If you get stuck on something: [Troubleshooting](/troubleshooting)


# Get started here

This page is designed to get your first app running in 15 minutes.

## Onboarding in 15 minutes (1 → 2)

{% hint style="info" %}
Follow the steps in order.
{% endhint %}

At the end, you will have:

* An app running on the **Preview** and **Browser**
* Three changes applied via **AI Chat**.

### Prerequisites (1 min)

* You have already created your account and are logged in.
* You can see the **Home** of Madrix.
* You have permission to create projects.

{% stepper %}
{% step %}

### Create your first project (5 min)

<sup>Prompt → Generate Software → Preview.</sup>

* [ ] Click New Project
* [ ] Paste the prompt below

```
Create a project named: TaskFlow

Goal: a simple task app.

Modules:
- Tasks

Entities:
- Task:
  - title (required)
  - description
  - status (New | In Progress | Review | Done)
  - priority (Low | Medium | High)
  - dueDate (date)
  - assignedTo (relationship: 1 User)

Business rules:
- The status may only advance in this order:
  New → In Progress → Review → Done
- Do not allow status to go backwards.

Minimum screens:
- Task list (filter by status and priority)
- Create/edit task
- Task detail

Reports: none.
```

* [ ] Click **Generate** (or press **Enter**)
* [ ] Wait for the requirements analyst agent to generate the app specification
* [ ] Review the specification and click **Approve**
* [ ] Watch the AI agents generate the app
* [ ] See the finished app on the **Preview** or click the **Run** <img src="/files/60a9b24094b4e5632ca096f03b2216e30892490f" alt="" data-size="original">
* [ ] Log in to the app with your **username** and **password**
* [ ] Create, edit and remove tasks from the task list and the kanban

**Expected result:** you can navigate and use the app's features.
{% endstep %}

{% step %}

### Evolve your project (8 min)

<sup>Using Chat AI mode</sup>

* [ ] In the Chat, write this prompt: "add an attachment field to the task component"
* [ ] Wait for the analyst agent to request approval for this app change
* [ ] Approve the change request
* [ ] Run the app and see in the task form that there is now a field to add files

Now apply one more change:

* [ ] In the Chat, write this prompt: "Add project registration and association of activities with projects"
* [ ] Wait for the change request and approve
* [ ] Run the app and validate:
  * There is a registration/list of **Projects**
  * When creating or editing **Tasks**, you can associate a **Project**

Now apply one last change (theme):

* [ ] In the toolbar click Project Settings ![](/files/48063584f45bd819a0d1a444f0b88f63b71cd201)
* [ ] Click **Visual Identity** and scroll the scrollbar to the *Theme Colors*
* [ ] Select the **primary** and **secondary** and click the **Save**
* [ ] Run the app and confirm the color change (buttons, header, highlights)

**Expected result:** you can apply three changes to your project.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Want to publish to the Cloud? Follow the tutorial **"Publish to the Cloud (first deploy)"** on [Practical Tutorials](/hands-on-tutorials).

On the same page, you also learn how to:

* Make more changes to your project
* Create more advanced projects (models, UI, workflows, integrations).
* Work in **Editor** mode for advanced adjustments.
  {% endhint %}

### If something goes wrong (2 min)

* **Nothing generated after the prompt:** try again with a shorter prompt. Reload the page.
* **Preview won't open:** disable adblock for the domain. Test in an incognito tab.

Proceed with:

* [Practical Tutorials](/hands-on-tutorials)
* [Demonstrations](/demonstrations)
* [Troubleshooting](/troubleshooting)

Troubleshooting shortcuts:

* If generation stalls: [AI generation failures](/troubleshooting/ai-generation-failures)


# Hands-on Tutorials

Detailed, consultative guides to master every aspect of the Madrix platform.

{% hint style="info" %}
If you're just starting out, do [Start here](/get-started-here) first.
{% endhint %}

### Shortcuts (if you already know what you want)

* **Write a “good” prompt and generate from scratch:** [Prompt tips](/hands-on-tutorials/1.-prompt-tips)
* **Evolve an existing app (small changes):** [Quick prompts](/hands-on-tutorials/2.-quick-prompts)
* **Publish to the Cloud (first deploy):** [Deploy and Cloud Environments](/hands-on-tutorials/3.-deployment-and-cloud-environments)
* **Advanced adjustments (when Chat doesn't solve it):** [Using Editor Mode](/hands-on-tutorials/5.-using-editor-mode)

### Choose a tutorial

<table data-view="cards"><thead><tr><th>Tutorial</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td><strong>1. Prompt tips</strong><br>Clear, testable prompts that are easy to iterate.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/8b5ad70a297e68ac5f8c16bf515fb317b9a20172">/spaces/jLpkUQEEJ5BcMqj70lza/pages/8b5ad70a297e68ac5f8c16bf515fb317b9a20172</a></td></tr><tr><td><strong>2. Quick prompts</strong><br>Copyable prompts to evolve an existing project.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/daf0ba5d784d2f1af1238c66d79ae1add8d1b875">/spaces/jLpkUQEEJ5BcMqj70lza/pages/daf0ba5d784d2f1af1238c66d79ae1add8d1b875</a></td></tr><tr><td><strong>3. Deploy and Cloud Environments</strong><br>From Preview to Cloud (Dev/Staging/Prod).</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/8dc21bf0e3f5d240f35fadfd0754d277c3485d86">/spaces/jLpkUQEEJ5BcMqj70lza/pages/8dc21bf0e3f5d240f35fadfd0754d277c3485d86</a></td></tr><tr><td><strong>4. Prompt Templates</strong><br>Copyable templates to generate complete apps (CRM, ERP, Helpdesk, OKRs and more).</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/c6e6d14e16ef83dbec397bd92277667966d87602">/spaces/jLpkUQEEJ5BcMqj70lza/pages/c6e6d14e16ef83dbec397bd92277667966d87602</a></td></tr><tr><td><strong>5. Using Editor Mode</strong><br>Advanced adjustments with assistant + editor.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/c51996ab7a0c38c1852153c7dae92d333111c436">/spaces/jLpkUQEEJ5BcMqj70lza/pages/c51996ab7a0c38c1852153c7dae92d333111c436</a></td></tr></tbody></table>

### Quick references (for consulting, not for “step-by-step” following)

* Platform blocks (projects, modules, entities, UI, rules, permissions): [Platform](/documentation/platform)
* Generation and iteration flow via chat: [AI Chat Mode](/documentation/chat-ai-mode)
* Advanced project adjustments (structure and editing): [Editor Mode](/documentation/editor-mode)
* Project settings (environments, visual identity, etc): [Project Settings](/documentation/project-settings)
* Running app settings (security, authentication, runtime): [Runtime Settings](/documentation/runtime-settings)
* Connect with external systems: [Integrations](/documentation/integrations-and-api)

### Next steps

* Want to see the full flow (prompt → deploy): [Demonstrations](/demonstrations)
* Want ready-made prompts to speed up: [Prompt Templates](/hands-on-tutorials/4.-prompt-templates)
* Stuck on something: [Troubleshooting](/troubleshooting)


# 1. Prompt tips

How to write clear, testable prompts that are easy to iterate on.

Use this page to write prompts that become **good specifications**.\
Then use the AI Chat to iterate on small changes.

{% hint style="info" %}
Want complete prompts by domain (CRM, ERP, Helpdesk, OKRs)? Also use [Prompt Templates](/hands-on-tutorials/4.-prompt-templates).
{% endhint %}

### Principles (what changes the outcome most)

1. **Write testable requirements.** Replace “well done” with objective criteria.
2. **Use lists and enums.** They reduce interpretation and “creativity”.
3. **Say what is not allowed.** Ex: “do not allow status rollback”.
4. **Start small.** Generate the “minimum that works”. Then evolve.
5. **Iterate by block.** Field + validation + UI tweak. One change at a time.

### Recommended format (base prompt)

Copy and adjust. It works well for initial generation.

```
Create a project called: {{PROJECT_NAME}}

Goal: {{DESCRIBE_IN_1_2_LINES}}
UI language: pt-BR.

Profiles (RBAC):
- Admin: full access
- Operator: creates/edits
- Reader: read-only

Modules:
- {{MODULE_1}}
    Entities:
    - {{ENTITY_1}}:
      - {{field}} (required)
      - {{field}} (unique, optional)
      - {{field}} (enum: A | B | C)
      - {{relationship}} (relationship: 1 {{OtherEntity}})
    
    Business rules:
    - {{rule_1}} (if/then)
    - {{rule_2}} (allowed transitions)
    
     Reports:
    - {{report_1}}
    - {{report_1}}

- {{MODULE_2}}
    Entities:
    - {{ENTITY_1}}:
      - {{field}} (required)
      - {{field}} (unique, optional)
      - {{field}} (enum: A | B | C)
      - {{relationship}} (relationship: 1 {{OtherEntity}})
    
    Business rules:
    - {{rule_1}} (if/then)
    - {{rule_2}} (allowed transitions)
    
    Reports:
    - {{report_1}}
    - {{report_1}}


```

### How to reduce ambiguity (with examples)

#### Replace adjectives with rules

* Instead of: “nice and modern screen”
* Write: “theme with primary color #0EA5E9 and secondary #111827”

#### Declare rules “by role”

* “Operator creates and edits only records they created.”
* “Reader cannot create/edit/delete.”
* “Admin can reprocess integrations with errors.”

#### Specify status transitions

* Define the enum.
* Define the allowed transitions.
* Say who can transition.
* Say what happens on transition (log, notifications, etc).

### Checklist before sending the prompt

* [ ] Goal and scope in 1–2 lines.
* [ ] Modules listed.
* [ ] Entities with fields and clear types (enum, date/time, currency).
* [ ] Relationships with cardinality (1, 0..1, N).
* [ ] Business rules in bullets “if/then”.
* [ ] Explicit RBAC (who sees what, who edits what).

{% hint style="warning" %}
Avoid asking for “everything” in a single prompt. If scope grows, split into 3–5 changes.
{% endhint %}


# 2. Quick prompts

Use these prompts in Chat AI to evolve an existing project.

Use this page to request **quick changes** to an already generated app. Paste **one prompt at a time**. Validate in Preview. Repeat.

{% hint style="info" %}
Want to improve the quality of requests? See [Prompt tips](/hands-on-tutorials/1.-prompt-tips).\
Want complete templates by domain? Use [Prompt Templates](/hands-on-tutorials/4.-prompt-templates).
{% endhint %}

### Placeholders (replace before sending)

* `{{Entidade}}`: name of the entity (e.g.: `Contract`).
* `{{novoCampo}}`: name of the field (e.g.: `signatureDate`).
* `{{NomeRelatorio}}`: name of the report.
* `{{evento}}`: name of the event (e.g.: `order.created`).
* `{{campo}}`: field used for search.
* `{{texto|numero|data|moeda|boolean|enum}}`: choose a type.

### UI and identity

<details>

<summary>Add languages</summary>

```
Add support for the following languages: pt-BR and en-US.
```

</details>

<details>

<summary>Customize visual identity (theme)</summary>

```
Update the app's visual identity.
Set primary color: #0EA5E9.
Set secondary color: #111827.
```

</details>

<details>

<summary>Background image on the login screen</summary>

```
On the login screen, add a background image.
Requirements:
- Responsive (desktop and mobile).
- Maintain contrast and form legibility.
- Do not impact the authentication flow.
```

</details>

### Security and permissions

<details>

<summary>Add roles and permissions (RBAC)</summary>

```
Implement RBAC with these roles:
- Admin: full access.
- Manager: sees everything for the team.
- Operator: creates/edits only records they created.
- Reader: read-only.

Rules:
- Operator cannot delete.
- Manager can reassign the responsible user.
- Create a simple screen for managing roles/permissions (Admin only).
```

</details>

### Structure (modules, entities and lists)

<details>

<summary>Add a module + menus</summary>

```
Create a new module called: Contracts.
Add menus and minimal screens (list + create/edit + detail) for the module.
```

</details>

<details>

<summary>Add field to an entity (with validation + UI)</summary>

```
In the {{Entidade}} entity, add the field {{novoCampo}}.
Type: {{texto|numero|data|moeda|boolean|enum}}.
Rules:
- Required.
- Minimum/maximum value: {{if applicable}}.
Update the forms and list to display the field.
```

</details>

<details>

<summary>Add query/filter (list)</summary>

```
In the {{Entidade}} list, add filters:
- status (multi-select)
- period (start and end date)
Add search by {{campo}}.
```

</details>

### Rules and reports

<details>

<summary>Business rule (status workflow)</summary>

```
For {{Entidade}}, implement a status workflow.
Enum: New | In Progress | Review | Completed.
Allowed transitions:
- New -> In Progress
- In Progress -> Review
- Review -> Completed
Block any transition outside this order.
Record change history (author + date/time + fromStatus + toStatus).
```

</details>

<details>

<summary>Simple report (with filters)</summary>

```
Create a report called: {{NomeRelatorio}}.
Metric: {{e.g.: total by status, total by month, top 10}}.
Filters: period and status.
Display on a basic dashboard.
```

</details>

### Integrations

<details>

<summary>Integration (webhook + log + reprocess)</summary>

```
Add an integration via webhook to the event: {{evento}}.
Requirements:
- Endpoint configurable by environment (Dev/Staging/Prod).
- Log payload, status and errors.
- Allow reprocessing of failed events (Admin only).
```

</details>

{% hint style="warning" %}
Avoid requesting “everything” in a single prompt. If the scope grows, break it into 3–5 changes.
{% endhint %}


# 3. Deployment and Cloud Environments

Provision a Cloud environment (Dev/Staging/Prod) and perform the first deploy.

### Prerequisites

* Your project already runs on **Preview**.
* You have permission to **purchase/provision** environments (billing).
* (Optional) You have access to **DNS** of the domain, if using a custom domain.

{% hint style="info" %}
**Dev** to test quickly. **Staging** to validate release. **Prod** for end users.
{% endhint %}

{% stepper %}
{% step %}

### Open Cloud Environments

* [ ] Go to **Project Settings → Cloud Environments**
  {% endstep %}

{% step %}

### Create the environment

* [ ] Click **Purchase Environment**
* [ ] Set the **name** of the environment (e.g.: `dev-myapp`, `staging-myapp`, `prod-myapp`)

{% hint style="info" %}
Choose a name that makes the environment type obvious. Prevents deploying to the wrong place.
{% endhint %}
{% endstep %}

{% step %}

### Configure domain and scaling

* [ ] (Optional) Configure a **domain** (if you want a custom URL)
* [ ] Configure the **scaling**

{% hint style="info" %}
Start smaller. Increase later if there is slowness, timeouts, or real load.
{% endhint %}
{% endstep %}

{% step %}

### Provision and wait until Ready

* [ ] Proceed with provisioning
* [ ] Wait for the status to become **Ready**

<details>

<summary>Expected time</summary>

Usually takes a few minutes. If it stays stuck for a long time, follow the "If it fails" section.

</details>
{% endstep %}

{% step %}

### Publish (deploy)

* [ ] Click **Publish** and deploy your project to this environment

{% hint style="info" %}
Avoid "deploy spam." If needed, wait a few minutes and try again.
{% endhint %}
{% endstep %}

{% step %}

### Validate the deploy

* [ ] Open the **URL** of the domain
* [ ] Confirm that the home page loads
* [ ] Log in and validate a critical flow (e.g.: create/edit a record)
  {% endstep %}
  {% endstepper %}

### If it fails

* **Deploy fails with error:** follow [Deployment issues](/troubleshooting/deploy-issues).
* **Environment “Ready”, but the URL doesn't open:** if using a custom domain, review DNS and wait for propagation.
* **Deploy completes, but the app doesn't start:** treat as a **runtime** and follow the diagnosis in the troubleshooting.


# 4. Prompt Templates

Copyable templates to generate complete apps (CRM, ERP, Helpdesk, OKRs and more).

Copy a template. Adjust the placeholders. Generate the app. Then iterate on the specification.

{% hint style="info" %}
Want to see the full flow (prompt → deploy)? Combine with [Demonstrations](/demonstrations).
{% endhint %}

### How to use (30s)

{% stepper %}
{% step %}

### Choose a template and define the scope

Decide modules and the “minimum that needs to work”. Avoid asking for everything on the first generation.
{% endstep %}

{% step %}

### Replace the placeholders and paste into Madrix

Replace `{{NOME_DO_PROJETO}}`, `{{IDIOMA_UI}}` and `{{PERFIS}}`. Paste the prompt and click **Generate**.
{% endstep %}

{% step %}

### Approve the specification and validate in the Preview

Validate entities, rules and permissions. Then validate the basics in the Preview with test data.
{% endstep %}

{% step %}

### Iterate with small changes

Request adjustments by block. Example: “add field X + validation + adjust form”.
{% endstep %}
{% endstepper %}

### Placeholders (default)

Use these markers to customize quickly.

* `{{NOME_DO_PROJETO}}`: project name.
* `{{IDIOMA_UI}}`: `pt-BR` or `en-US`.
* `{{PERFIS}}`: system roles. Ex: `Admin`, `Manager`, `Operator`.
* `{{REGRAS_DE_NEGOCIO}}`: “if/then” rules and transitions.
* `{{INTEGRACOES}}`: webhooks, import, external APIs.

### Generic examples (copy and paste)

Use when you don’t yet have a domain template. These are neutral blocks to compose your app.

<details>

<summary>Generic — CRUD + permissions (quick)</summary>

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: simple CRUD app, with profile-based permissions and basic validations.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin: full access
- Operator: create/edit records
- Reader: read-only

Entities:
- Record:
  - title (required)
  - description
  - status (Active | Inactive)
  - createdAt (date/time)
  - createdBy (1 User)

Business rules:
- Operator can only edit records they created.
- Reader cannot create/edit/delete.

Minimum screens:
- Record list (filters by status + search by title)
- Create/edit record (validations)
- Record detail

Acceptance criteria:
- Admin sees everything.
- Operator creates and edits only what they created.
- Reader can list and open detail, without editing.
```

</details>

<details>

<summary>Generic — workflow (states + transitions)</summary>

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: app with workflow and a simple approval trail.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin
- Requester
- Approver

Entities:
- Request:
  - title (required)
  - description
  - amount (currency, optional)
  - status (Draft | Submitted | Approved | Rejected | Cancelled)
  - requester (1 User)
  - approvedBy (0..1 User)
  - createdAt (date/time)

- StatusHistory:
  - request (1 Request)
  - fromStatus
  - toStatus
  - author (1 User)
  - comment
  - createdAt (date/time)

Business rules:
- Allowed transitions:
  - Draft -> Submitted
  - Submitted -> Approved | Rejected
  - Draft -> Cancelled
  - Submitted -> Cancelled (Admin only)
- Only Approver can approve/reject.
- Always record StatusHistory on any transition.

Minimum screens:
- My requests (requester)
- Approval queue (approver)
- Request detail + status history

Acceptance criteria:
- Requester submits and cannot edit after Submitted.
- Approver approves/rejects with a comment.
- History lists all status changes.
```

</details>

<details>

<summary>Generic — integrations (webhook/API + log + reprocess)</summary>

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: app with external integration via webhook/API, with logging and reprocessing.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin
- Operator

Entities:
- IntegrationEvent:
  - type (Outbound | Inbound)
  - system (required)
  - event (required)
  - payload (text/json)
  - status (Pending | Success | Error)
  - attempts (number)
  - lastError
  - createdAt (date/time)
  - processedAt (date/time, optional)

Integration flow:
- When creating/updating a Record, trigger an Outbound event.
- Send payload to a configurable endpoint (per environment).
- Record success/error in IntegrationEvent.
- Allow “Reprocess” for events with Error status.

Business rules:
- Maximum of 5 attempts per event.
- Only Admin can manually reprocess.

Minimum screens:
- Settings: endpoints per environment (Dev/Staging/Prod)
- Integrations log (filter by status + system + period)
- Event detail (payload + errors + reprocess button)

Acceptance criteria:
- A failure creates an Error event with a message.
- Admin can reprocess and see status become Success.
```

</details>

***

<details>

<summary>Clinic 360</summary>

**When to use**

* Clinic or practice.
* Schedule + care + simple billing.
* Control by profile and basic auditing.

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: clinic system with scheduling, care and simple billing.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin: full access
- Reception: schedule and patient registration
- HealthProfessional: medical record and appointments
- Finance: billing and payments

Modules:
- Schedule
- Patients
- Appointments (medical record)
- Billing

Entities:
- Patient:
  - fullName (required)
  - cpf (unique, required)
  - birthDate (date)
  - phone
  - email
  - notes

- Professional:
  - fullName (required)
  - specialty
  - councilRegistration

- Appointment:
  - patient (relationship: 1 Patient)
  - professional (relationship: 1 Professional)
  - start (date/time)
  - end (date/time)
  - status (Scheduled | Confirmed | InService | Completed | Cancelled)
  - cancellationReason

- Service:
  - patient (1 Patient)
  - professional (1 Professional)
  - dateTime (date/time)
  - mainComplaint
  - progressNotes
  - prescription
  - attachments (optional)

- Invoice:
  - patient (1 Patient)
  - service (0..1 Service)
  - amount (currency)
  - status (Open | Paid | Cancelled)
  - dueDate (date)
  - paymentMethod (Pix | Card | Cash | Boleto)

Business rules:
- Prevent double booking of the same professional at the same time.
- Reception cannot see clinical fields of the Service.
- Finance cannot edit Services.

Minimum screens:
- Schedule calendar (day/week) with quick creation
- Patient list + create/edit
- Check-in: convert Appointment to Service
- Patient medical record (timeline of services)
- Billing: invoice list + mark as paid

Acceptance criteria:
- User with Reception profile can schedule and confirm.
- HealthProfessional can record service and complete it.
- Finance can record payment and list pending items.
```

**Common extensions**

* Reminders (WhatsApp/email) for appointments.
* Terms and consents with acceptance.
* Multi-unit (branch) and schedule per unit.

</details>

<details>

<summary>CRM 360</summary>

**When to use**

* B2B sales.
* Pipeline with activities.
* Goals dashboard.

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: sales CRM with pipeline, activities and reports.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin: full access
- SalesManager: manages pipeline and goals
- Seller: manages their leads and opportunities
- SDR: qualifies leads and schedules meetings

Modules:
- Records
- Pipeline
- Activities
- Reports

Entities:
- Company:
  - name (required)
  - cnpj (unique, optional)
  - segment
  - size (Small | Medium | Large)

- Contact:
  - company (1 Company)
  - name (required)
  - email
  - phone
  - position

- Lead:
  - name (required)
  - origin (Inbound | Outbound | Referral | Event)
  - status (New | Qualified | Discarded | Converted)
  - owner (relationship: 1 User)
  - company (0..1 Company)
  - contact (0..1 Contact)

- Opportunity:
  - title (required)
  - company (1 Company)
  - estimatedValue (currency)
  - probability (0..100)
  - stage (Prospecting | Diagnosis | Proposal | Negotiation | ClosedWon | ClosedLost)
  - owner (1 User)
  - lossReason
  - expectedCloseDate (date)

- Activity:
  - type (Call | Email | Meeting | Task)
  - relatedTo (Lead or Opportunity)
  - owner (1 User)
  - dateTime (date/time)
  - status (Pending | Completed | Cancelled)
  - notes

Business rules:
- Seller only sees and edits records where they are the owner.
- SalesManager sees the whole team’s data.
- Stage can only advance. Do not allow moving back.

Minimum screens:
- Opportunities Kanban by stage
- Lead list + qualify/discard/convert to Opportunity
- Activities schedule (my activities)
- Dashboard: pipeline by stage + forecasted revenue per month

Acceptance criteria:
- SDR can qualify lead and convert.
- Seller can move opportunity in the Kanban.
- SalesManager can see the team’s consolidated pipeline.
```

**Common extensions**

* Lead import (CSV).
* WhatsApp integration.
* Commissions per seller.

</details>

<details>

<summary>ERP 360</summary>

**When to use**

* Operations with sales, purchases and inventory.
* Basic finance (accounts payable/receivable).

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: simple ERP with catalog, purchasing, sales, inventory and basic finance.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin: full access
- Purchasing: purchase orders and suppliers
- Sales: sales orders and customers
- Inventory: movements and inventory
- Finance: accounts payable/receivable

Modules:
- Records
- Purchasing
- Sales
- Inventory
- Finance

Entities:
- Product:
  - sku (unique, required)
  - name (required)
  - unit (UN | BX | KG | LT)
  - salePrice (currency)
  - standardCost (currency)
  - active (boolean)

- Customer:
  - name (required)
  - document (cpf/cnpj)
  - email
  - phone

- Supplier:
  - name (required)
  - document (cpf/cnpj)
  - email
  - phone

- SalesOrder:
  - customer (1 Customer)
  - status (Draft | Approved | Invoiced | Cancelled)
  - orderDate (date)
  - total (currency)

- SalesOrderItem:
  - salesOrder (1 SalesOrder)
  - product (1 Product)
  - quantity (number)
  - unitPrice (currency)

- PurchaseOrder:
  - supplier (1 Supplier)
  - status (Draft | Approved | Received | Cancelled)
  - orderDate (date)
  - total (currency)

- PurchaseOrderItem:
  - purchaseOrder (1 PurchaseOrder)
  - product (1 Product)
  - quantity (number)
  - unitCost (currency)

- InventoryMovement:
  - product (1 Product)
  - type (In | Out | Adjustment)
  - quantity (number)
  - dateTime (date/time)
  - reference (PurchaseOrder or SalesOrder, optional)

- FinancialEntry:
  - type (Payable | Receivable)
  - status (Open | Paid | Cancelled)
  - amount (currency)
  - dueDate (date)
  - paymentDate (date, optional)
  - origin (PurchaseOrder or SalesOrder, optional)

Business rules:
- When receiving a PurchaseOrder: generate Stock In.
- When invoicing a SalesOrder: generate Stock Out and an Accounts Receivable entry.
- Prevent negative stock.

Minimum screens:
- Product/customer/supplier registration
- Purchase order (with items) + receiving
- Sales order (with items) + invoicing
- Inventory: position by product + movement list
- Finance: open entries (payable/receivable)

Acceptance criteria:
- Purchasing can approve and receive an order.
- Sales can invoice and deduct stock.
- Finance can list open entries and mark as paid.
```

**Common extensions**

* Multiple warehouses.
* Lots and expiration dates.
* Cost center and chart of accounts.

</details>

<details>

<summary>Satellite ERPs</summary>

**When to use**

* You already have an ERP.
* You need quick satellite apps.
* You want to avoid “touching the core”.

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: satellite app integrated with the current ERP, focused on a specific process.
UI language: {{IDIOMA_UI}}.

Target process (describe clearly):
- Example: purchase requisition and approval by authority levels.

Profiles (RBAC):
- Admin
- Requester
- Approver
- Purchasing

Entities:
- PurchaseRequisition:
  - requester (1 User)
  - costCenter
  - status (Draft | Submitted | Approved | Rejected | SentToERP)
  - estimatedValue (currency)
  - justification
  - createdAt (date/time)

- PurchaseRequisitionItem:
  - requisition (1 PurchaseRequisition)
  - description (required)
  - quantity (number)
  - unit (UN | BX | KG | LT)
  - estimatedPrice (currency)

Integrations:
- {{INTEGRACOES}}
- Example: on approval, call the ERP API to create an official request.

Business rules:
- Approval by authority levels:
  - amount <= 5,000: 1 approver
  - amount > 5,000: 2 levels
- Do not allow editing after Submitted.

Minimum screens:
- Create/edit requisition with items
- Approval screen (approver queue)
- History and trail (who approved, when, comment)
- Integrations: log of calls to the ERP (success/error)

Acceptance criteria:
- Requester creates and submits.
- Approver approves/rejects with a comment.
- After approval, the requisition is sent to the ERP and the status is recorded.
```

**Common extensions**

* Upload attachments (3 quotes).
* SLA and notifications.
* Reprocessing of failed integrations.

</details>

<details>

<summary>HelpDesk 360</summary>

**When to use**

* Internal or customer support.
* SLAs and queues.
* Simple knowledge base.

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: helpdesk with tickets, queues, SLAs and macros.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin
- Agent: handles tickets
- Supervisor: manages queues and reports
- Requester: opens and follows up tickets

Modules:
- Tickets
- SLAs
- Knowledge base
- Reports

Entities:
- Ticket:
  - number (unique)
  - subject (required)
  - description
  - priority (Low | Medium | High | Critical)
  - status (Open | InService | WaitingCustomer | Resolved | Closed)
  - requester (1 User)
  - agent (0..1 User)
  - queue (1 Queue)
  - category
  - tags
  - createdAt (date/time)
  - updatedAt (date/time)

- TicketComment:
  - ticket (1 Ticket)
  - author (1 User)
  - visibility (Internal | Public)
  - text (required)
  - createdAt (date/time)

- Queue:
  - name (required)
  - slaFirstResponseHours (number)
  - slaResolutionHours (number)

- Macro:
  - name (required)
  - defaultText
  - changeStatusTo (optional)

Business rules:
- Requester only sees their own tickets.
- Agent sees tickets from their queue.
- Status only advances. Do not allow reverting from Closed.

Minimum screens:
- Open ticket (requester)
- My requests (requester)
- Ticket queue (agent)
- Ticket screen with internal vs public comments
- Dashboard: backlog by queue, SLA violations, average resolution time

Acceptance criteria:
- Requester opens a ticket and follows the status.
- Agent responds using Macro.
- Supervisor sees SLA reports by queue.
```

**Common extensions**

* Dynamic form by category.
* Routing rules for queues.
* Search and articles in the knowledge base.

</details>

<details>

<summary>OKR 360</summary>

**When to use**

* Goals management by cycles.
* Follow-up with check-ins.
* View by team and company.

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Goal: OKR system with cycles, objectives, key results and check-ins.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin
- Leader: creates and follows the team’s OKRs
- Member: updates their KRs and check-ins

Modules:
- Cycles
- OKRs
- Check-ins
- Reports

Entities:
- Cycle:
  - name (required)
  - start (date)
  - end (date)
  - status (Planning | InProgress | Closed)

- Objective:
  - cycle (1 Cycle)
  - title (required)
  - description
  - team
  - owner (1 User)
  - status (Active | Paused | Completed)

- KeyResult:
  - objective (1 Objective)
  - title (required)
  - type (Number | Percentage | Currency)
  - baseline (number)
  - target (number)
  - current (number)
  - status (OnTrack | AtRisk | OffTrack | Completed)

- CheckIn:
  - keyResult (1 KeyResult)
  - author (1 User)
  - date (date)
  - comment
  - currentValue (number)

Business rules:
- Closing a cycle blocks editing Objectives/KRs.
- Current KR value must be updated via CheckIn.

Minimum screens:
- Cycle planning (list of objectives + KRs)
- OKR view by team
- Weekly check-in (simple form)
- Cycle dashboard (aggregate progress, KRs at risk)

Acceptance criteria:
- Leader creates objectives and KRs for the cycle.
- Member does check-in and updates the KR value.
- Dashboard shows KRs at risk and progress.
```

**Common extensions**

* Weights by KR and objective score.
* Integration with Jira/Linear for evidence.
* Comments and alignment (parent/child OKR).

</details>

<details>

<summary>ProjectHub 360</summary>

**When to use**

* Projects with tasks, sprints and roadmap.
* An internal "simple Jira."

**Base prompt (copy and paste)**

```
Create a project called: {{NOME_DO_PROJETO}}

Objective: project management with backlog, sprints and roadmap.
UI language: {{IDIOMA_UI}}.

Profiles (RBAC):
- Admin
- PM: manages roadmap and sprints
- Dev: executes tasks and updates status
- Stakeholder: read-only and comments

Modules:
- Backlog
- Sprints
- Roadmap
- Reports

Entities:
- Project:
  - name (required)
  - description
  - status (Active | Paused | Closed)

- Sprint:
  - project (1 Project)
  - name (required)
  - start (date)
  - end (date)
  - status (Planned | InProgress | Closed)

- BacklogItem:
  - project (1 Project)
  - type (Epic | Story | Bug | Task)
  - title (required)
  - description
  - priority (Low | Medium | High)
  - status (Backlog | InProgress | InReview | Done)
  - assignee (0..1 User)
  - sprint (0..1 Sprint)
  - estimatePoints (number, optional)

- Comment:
  - item (1 BacklogItem)
  - author (1 User)
  - text (required)
  - createdAt (date/time)

Business rules:
- Status can only advance: Backlog -> InProgress -> InReview -> Done.
- Stakeholder cannot edit items. Only comment.

Minimum screens:
- Backlog with filters and quick creation
- Board (kanban) per sprint
- Item detail with comments
- Simple roadmap (epics by period)
- Report: throughput per sprint + items in WIP

Acceptance criteria:
- PM creates sprint and pulls items from the backlog.
- Dev moves items on the board respecting transitions.
- Stakeholder can follow and comment.
```

**Common extensions**

* Dependencies between items.
* SLAs for bugs.
* Integration with GitHub (PR/commit link).

</details>


# 5. Using Editor Mode

How to adjust backend (modules, entities, fields, scripts) and understand the frontend scaffold.

Use the **Editor Mode** for “surgical” adjustments to what the AI generated. Use the **AI Chat** for larger changes, with multiple screens and rules.

{% hint style="info" %}
If you want the complete reference (field types, events and structure), also see [**Editor Mode**](/documentation/editor-mode).
{% endhint %}

### Prerequisites

* You have edit permission on the project.
* Your app opens in **Preview**.

### Backend (final example)

Example goal: a **Task Manager** module with entity **Task**, common fields, relationship and status rule.

{% stepper %}
{% step %}

### 1) Adjust the module and menus

In the Editor, open **Modules** and edit (or create) a module:

* **Module name:** `Tasks`
* **Icon:** choose one that makes the card easy to identify.
* **Display Name Translations:**
  * `pt-BR`: `Tasks`

Create a menu inside the module:

* **Name:** `My tasks`
* **URL Path:** `/tasks`

{% hint style="warning" %}
Avoid changing the **URL Path** later. This breaks links and bookmarks.
{% endhint %}

**Expected result:** the module card appears on the Home. The menu navigates.
{% endstep %}

{% step %}

### 2) Create/adjust the component (entity)

Create a **Component**:

* **Name (lowercase):** `task`
* **Module:** `Tasks`
* **Display Name Translations:**
  * `pt-BR`: `Task`

When saving, use these options (when they appear):

* **Create frontend files:** yes (if you want scaffolded screens)
* **Create menu automatically:** optional (if you already created the menu manually)

**Expected result:** the component exists and already has UI structure (if checked).
{% endstep %}

{% step %}

### 3) Model fields (with ready examples)

Inside `task`, create the fields below:

* `title`
  * **Type:** `String`
  * **Required:** yes
* `description`
  * **Type:** `Text`
* `status`
  * **Type:** `Picklist`
  * **Options:** `New | In Progress | Review | Completed`
  * **Required:** yes
* `priority`
  * **Type:** `Picklist`
  * **Options:** `Low | Medium | High`
* `dueDate`
  * **Type:** `Date`
* `assignedTo`
  * **Type:** `User`
* `attachments`
  * **Type:** `Attachments`

Quick tip:

* If the list becomes “tight”, adjust the **Grid Width** per field.

**Expected result:** the Task form has all fields. The list shows the main ones.
{% endstep %}

{% step %}

### 4) Add a (1-N) relationship with Project

Create a second component:

* **Name:** `project`
* Minimum fields:
  * `name` (`String`, required, unique)

Now go back to `task` and create a field:

* `project`
  * **Type:** `Component`
  * **Related component:** `project`
  * **Cardinality:** 1 (a task belongs to a project)
  * **Display Field:** `name`

{% hint style="danger" %}
Only check `deleteCascade` if you accept deleting data in bulk.
{% endhint %}

**Expected result:** in the Task form, you select a Project.
{% endstep %}

{% step %}

### 5) Create a reusable query (optional but useful)

In `task`, create a **Query** called `Overdue`:

* Filter: `dueDate` less than today
* And `status` not equal to `Completed`

**Expected result:** you reuse this filter in lists and reports.
{% endstep %}

{% step %}

### 6) Business rule via Script (no “code” in the frontend)

Example rule: **do not allow status regression**.

Implement as a script in the component event `task`:

* Recommended event: **Before Update**
* Validation:
  * Allow only progression: `New → In Progress → Review → Completed`
  * Block any regression
* Clear error message:
  * “Status rollback is not allowed.”

Test in Preview:

* Create a task in `New`
* Advance to `In Progress`
* Try to go back to `New` and validate the block

**Expected result:** the rule works in the backend. It applies to UI and API.
{% endstep %}
{% endstepper %}

### Frontend (generated scaffold)

The scaffold only exists if you checked **Create frontend files** when saving the component.

#### What you get (summary)

* Base app routes.
* Pages protected by module.
* Forms and lists generated per component.
* Base theme and styles.

<details>

<summary>Where your module screens are usually located</summary>

Look for a structure like:

* `pages/protected/`
  * `{module}/` (e.g.: `tasks/`)
    * list, create and edit screens

</details>

#### What to edit vs what to avoid

Edit safely:

* Module pages (screens).
* UI components of your app.
* Theme (colors, typography).

Avoid editing:

* Files marked as **locked** (managed by the platform).

#### Validation checklist (Preview)

* [ ] Module card appears on the Home.
* [ ] Menu opens the listing.
* [ ] Create/edit Task works.
* [ ] Picklists have the correct options.
* [ ] Relationship with Project selects and saves.
* [ ] Status rule blocks regression.

{% hint style="info" %}
If the goal is to change only theme and texts, this is usually faster in **Project Settings**.
{% endhint %}


# Demonstrations

Learn by watching real systems being created, from prompt to deploy, with use cases by industry.

### How to use this page

Use these demos to see the full flow. You go from prompt to deploy, with real examples.

{% hint style="info" %}
If you just want to “see it working”, start with **Start here**.
{% endhint %}

### Start here (recommended)

These three demos cover 80% of what you need.

1. **Sales CRM (from scratch)**\
   Prompt → specification → app → preview.\
   Video: *coming soon*. Template: *coming soon*.
2. **Inventory + alerts + dashboard**\
   Minimum stock, automatic alerts, management view.\
   Video: *coming soon*. Template: *coming soon*.
3. **Approvals (discount > 10%) end-to-end**\
   Multi-level workflow, audit trail, permissions.\
   Video: *coming soon*. Template: *coming soon*.

### Demos by industry

Choose a sector and adapt the template.

* **Healthcare**\
  Electronic medical record, scheduling, profile-based permissions.\
  Video: *coming soon*. Template: *coming soon*.
* **Construction and engineering**\
  Project management, budgets, measurements and approvals.\
  Video: *coming soon*. Template: *coming soon*.
* **Finance**\
  Financial control, cost centers, approvals.\
  Video: *coming soon*. Template: *coming soon*.
* **Retail**\
  POS, inventory, promotions, discount rules.\
  Video: *coming soon*. Template: *coming soon*.
* **Logistics**\
  Tracking, routing, status and SLAs.\
  Video: *coming soon*. Template: *coming soon*.
* **Education**\
  Course platform, assessments, certificates.\
  Video: *coming soon*. Template: *coming soon*.

### Demos by use case

Grouped by “product” vs “capability”.

#### Products (complete apps)

* **CRM**\
  Customer management, pipeline and activities.\
  Video: *coming soon*. Template: *coming soon*.
* **Helpdesk**\
  Tickets, queues, SLAs and support macros.\
  Video: *coming soon*. Template: *coming soon*.
* **Portal**\
  Internal vs external access, self-service.\
  Video: *coming soon*. Template: *coming soon*.

#### Capabilities (reusable pieces)

* **Approvals (workflow)**\
  Multi-level approval by value, area, risk.\
  Video: *coming soon*. Template: *coming soon*.
* **RBAC (roles and permissions)**\
  Profiles, rules by entity, screen and action.\
  Video: *coming soon*. Template: *coming soon*.
* **API + Webhook (integrations)**\
  Events, external calls and synchronization with ERP/CRM.\
  Video: *coming soon*. Template: *coming soon*.

### How to run a demo (standard flow)

{% stepper %}
{% step %}

### Watch the video and copy the prompt

Find the demo video. Copy the original prompt and the acceptance criteria.
{% endstep %}

{% step %}

### Generate the app and approve the specification

Paste the prompt into Madrix. Approve the specification before proceeding.
{% endstep %}

{% step %}

### Run the app and validate the basics

Create test records. Validate permissions, rules and flows.
{% endstep %}

{% step %}

### Adapt to your scenario

Replace names, fields and rules. Add integrations and notifications afterward.
{% endstep %}

{% step %}

### Deploy to Cloud environment

Deploy to Dev/Staging/Prod. Collect evidence and audit trails if needed.
{% endstep %}
{% endstepper %}

### Assets per demo (checklist)

Use this list to standardize each demo.

* [ ] **Clonable template** (“use this demo as template”)
* [ ] **Original prompt** used in the video
* [ ] **Versions** (v1, v2, v3) with short changelog
* [ ] **Diff of what changed** between versions (when it makes sense)
* [ ] **Evidence package** (if it is a “production readiness” demo)

### Next steps

* Want to learn by doing: [Practical Tutorials](/hands-on-tutorials)
* Want to get started in 15 min: [Start here](/get-started-here)
* Stuck on something: [Troubleshooting](/troubleshooting)


# Documentation

Madrix documentation hub: platform, modes (Chat AI/Editor), settings and integrations.

***

### Summary

Use this section as an entry point to navigate the Madrix documentation.

Here you will find the platform concepts, usage modes and main configurations.

### Next steps

* Understand the platform mind map: [Platform](/documentation/platform)
* Generate and iterate with prompts: [AI Chat Mode](/documentation/chat-ai-mode)
* Make advanced adjustments: [Editor Mode](/documentation/editor-mode)
* Review the app settings: [Project Settings](/documentation/project-settings)
* Configure runtime (auth, security, etc): [Runtime Settings](/documentation/runtime-settings)
* Connect with external services: [Integrations and API](/documentation/integrations-and-api)
* If you get stuck on something: [Troubleshooting](/troubleshooting)


# Platform

Overview of the platform’s main building blocks (projects, modules, entities, UI, dashboards, rules and permissions).

Madrix is a platform for **designing, generating and operating** enterprise apps with AI.

Use this page as a mind map. It helps you navigate the blocks and flows.

Shortcuts:

* Generate and iterate in the chat: [AI Chat Mode](/documentation/chat-ai-mode)
* Advanced settings (backend + scaffold): [Editor Mode](/documentation/editor-mode)
* Project settings: [Project Settings](/documentation/project-settings)
* Runtime settings (security, auth, etc): [Runtime Settings](/documentation/runtime-settings)
* Connect with your stack: [Integrations](/documentation/integrations-and-api)

### End-to-end flow (the “happy path”)

1. **Login** to the platform.
2. Open the **Home**.
3. Enter **Projects** and create/select a project.
4. Generate and evolve via **AI Chat** (with approval checkpoints).
5. Test in the **Preview** with **Run**.
6. Deploy with **Publish** (when you want Cloud).

{% hint style="info" %}
If you want a step-by-step with ready prompts: [Start here](/get-started-here).
{% endhint %}

### Interface map (where things are)

#### Login

Platform entry. After login, you land on the **Home**.

#### Home

Starting point. Usually you do:

* Select a recent project.
* Create a new project.
* Open global settings (user/organization).

#### Projects

A **Project** is the “container” of your app. It stores:

* Structure (modules, entities/components, fields, scripts).
* Generated UI (screens, routes, menus).
* Settings and environments.

#### Project Editor (top bar)

This is the area where you switch between **generate** and **edit**.

Common items:

* **Project name**
* **Mode toggle**: AI Chat ↔ Editor
* **Run**: opens/refreshes the app Preview
* **Publish**: deploys to Cloud environment (when configured)
* **Home**: returns to Home
* **Notifications**
* **User/Organization settings**

#### User / Organization Settings

Where preferences and organization context live (e.g.: permissions, access, etc).

#### Selected language

Controls interface texts. Also interacts with translations like `pt-BR`, `en`, etc.

### Essential concepts (short definitions)

* **Project**: the entire app (code, data, settings and deploy).
* **Module**: a functional domain (e.g.: Sales, Tasks, Finance).
* **Entity / Component**: your main “object” (becomes a table in the database).
* **Field**: entity attribute (type, required, unique, picklist, etc).
* **Relationship**: connection between entities (1-N, N-N).
* **Script**: backend business rule (e.g.: validation and automation).
* **UI**: generated screens, routes, menus and forms.
* **Dashboard / Report**: managerial view and analyses.
* **Permissions (RBAC)**: who can see/do what.

### How AI generates systems in Madrix (mental model)

The flow tends to be this:

1. You describe objective, entities and rules in the prompt.
2. The platform generates a **specification** for you to approve.
3. After approval, agents generate backend + UI + project resources.
4. You test in the Preview and request incremental changes.

{% hint style="info" %}
Practical tip: treat the specification as a “contract”. It reduces rework.
{% endhint %}

### Common flows (when to use each mode)

#### AI Chat (large and iterative changes)

Use when you want to:

* Create an app from scratch.
* Add entire modules and entities.
* Refactor rules or flows.
* Request changes in “business language”.

Open: [AI Chat Mode](/documentation/chat-ai-mode)

#### Editor (“surgical” adjustments and fine control)

Use when you want to:

* Adjust fields, relationships, menus and event scripts.
* Understand the generated frontend scaffold.
* Resolve details the chat did not handle well.

Open: [Editor Mode](/documentation/editor-mode)

### AWUs (Agentic Work Units)

An AWU is the consumption unit for agentic work. In practice, it grows with:

* Scope of the request (number of modules/entities/screens).
* Number of iterations (changes that rewrite a lot).
* Complexity of rules, integrations and permissions.

Best practices to consume less:

* Start with a smaller prompt and evolve in steps.
* Approve the specification before generating.
* Make changes in small, testable “batches”.

{% hint style="warning" %}
Wide and vague change (“redo everything”) usually consumes more and breaks more things.
{% endhint %}

### Limits (limits, best practices and anti-patterns)

Use as a guardrail to have more predictability.

Best practices:

* Write prompts with **objective + entities + rules**.
* Prefer consistent names. Avoid synonyms for the same thing.
* Request changes in checklist format. This reduces ambiguity.
* Test in the Preview right after each batch of changes.

Anti-patterns:

* Requesting “a complete ERP” in a single prompt.
* Mixing many domains in the same first step.
* Changing names and structures “in bulk” without validating impact.
* Deploying without validating the Preview and basic permissions.

### Next steps

* Want to learn by doing: [Hands-on Tutorials](/hands-on-tutorials)
* Want to see real cases: [Demonstrations](/demonstrations)
* Stuck on something: [Troubleshooting](/troubleshooting)


# Chat AI Mode

The **AI Chat Mode** is where you describe what you want. The AI turns that into **specification**, **code**, and an app running on the **Preview**.

Use Chat AI to:

* Create an app from scratch.
* Make large changes (new modules, entities, screens).
* Iterate quickly with approval at each step.

{% hint style="info" %}
For “surgical” backend changes, use the [Editor Mode](/documentation/editor-mode).
{% endhint %}

### Prerequisites

* You have edit permission on the project.
* Your app opens in the **Preview**.

### Typical flow

{% stepper %}
{% step %}

### Write a prompt (intent + constraints)

Include:

* App goal.
* Modules and entities.
* Fields and types (e.g., `String`, `Date`, `Picklist`).
* Business rules (validations, states, permissions).

{% hint style="warning" %}
Avoid asking for “everything at once”. Break into changes of 1–3 items.
{% endhint %}
{% endstep %}

{% step %}

### Review the app specification

The analyst agent proposes a **App Specification**.

Review focusing on:

* Names of modules, entities and fields.
* Relationships (1-N, N-N) and required fields.
* Rules that need to become validations.
* What stays **out of scope**.

If something is wrong, correct it in the chat with clear instructions.
{% endstep %}

{% step %}

### Approve and follow the agentic coding

Upon approval, the agents begin generation.

You should:

* Wait for completion.
* Read the summary of what was changed.
* Validate whether the intent was met.
  {% endstep %}

{% step %}

### Test in Preview

Use Preview to validate the actual flow.

Quick checklist:

* Navigation (menus, routes).
* Basic CRUD (create/edit/list/remove).
* Business rules and validations.
* Perceived performance (lists, filters).
  {% endstep %}

{% step %}

### Make “Change Requests”

When you request an enhancement, the AI opens a **change request**.

Best practices:

* Write atomic changes.
* State what should change and what should remain.
* State how to validate: “expected result”.

Prompt examples:

* “Add a **attachments** in **Task**. Type attachments.”
* “Create the module **Projects** and relate **Task → Project** (1 project per task).”
* “Create a picklist **status** with: New | In Progress | Review | Done.”
  {% endstep %}
  {% endstepper %}

### Quick prompt tips

* Prefer imperative phrases: “create”, “add”, “change”, “remove”.
* Name entities and fields consistently.
* Always state the impact on screens: list, form, detail.
* When there is a rule: describe the **trigger** and the **expected error**.

### If something goes wrong

* If generation stalls or becomes inconsistent: see [AI generation failures](/troubleshooting/ai-generation-failures).
* If Preview doesn’t open: check extensions (adblock) and try an incognito window.

### Recommended readings

* First project in 15 min: [Start here](/get-started-here)
* How to write better prompts: [1. Prompt tips](/hands-on-tutorials/1.-prompt-tips)


# Editor Mode

The **Editor Mode** is where you adjust what the AI generated. Use for specific changes in the **backend**. Also use to understand the **frontend scaffold**.

### Prerequisites

* You have edit permission on the project.
* Your app opens in the **Preview**.

{% hint style="info" %}
Use Editor Mode for “surgical” adjustments. For large generation, prefer Chat AI.
{% endhint %}

### Typical flow

{% stepper %}
{% step %}

### Adjust module and menus

* Review the module card on the Home.
* Review menus and URL Path.
  {% endstep %}

{% step %}

### Create/adjust components (entities)

* Set name, module and display name.
* Connect scripts to component events.
  {% endstep %}

{% step %}

### Model fields and relationships

* Create fields and constraints (required, unique).
* Configure 1-N and N-N.
  {% endstep %}

{% step %}

### (Optional) Create queries

* Save queries to reuse in lists and reports.
  {% endstep %}

{% step %}

### Create reports and dashboards

* Use the visual editor to build reports and dashboards.
  {% endstep %}
  {% endstepper %}

### Backend

#### Modules

You can **add, edit and remove** modules.

In the module registration, you configure:

* **Module Name**
* **Icon**
* **Description**
* **Display Name Translations** (display name per language)

The **Display Name** appears in the **Home** as a module card.

Common languages in translations:

* `en` (English)
* `de` (German)
* `es` (Spanish)
* `fr` (French)
* `it` (Italian)
* `zh` (Chinese)
* `ja` (Japanese)
* `pt-BR` (Portuguese Brazil)
* `pt-PT` (Portuguese Portugal)

**Module menus**

Inside the module, you can register menus. Each menu has:

* **Name**
* **URL Path**
* **Icon**
* **Display Name Translations**

{% hint style="warning" %}
Changing **URL Path** can break existing links. Test the flow in Preview.
{% endhint %}

#### Components (entities)

A **Component** in Madrix is an entity. It represents a **table in the database** and can have **scripts** associated.

You can **add, edit and remove** components. In the component registration, you configure:

* **Name** (use lowercase)
* **Description**
* **Module**
* **Display Name Translations**
* Scripts per event:
  * **Before Insert**
  * **After Insert**
  * **Before Update**
  * **After Update**
  * **Before Delete**
  * **After Delete**

When saving a component, the system may ask:

* **Create frontend files**
* **Create menu automatically**
* **Menu icon**

#### Database

**Fields**

You can **add, edit and remove** component fields.

Each field usually has:

* **Name**
* **Type**
* Flag **Required**
* **Width in grid** (runtime)
* Flag **Unique** (do not allow duplicates)
* **Display Name Translations**

Field types:

* `String`
* `Boolean`
* `Date` (sets format)
* `Datetime` (sets format)
* `Decimal` (decimal places; currency flag)
* `Integer`
* `Picklist` (list of options)
* `Component` (relationship with another component)
* `User`
* `Attachments`
* `Text`

Examples:

* `Picklist`: **Priority** = `High | Medium | Low`
* `Decimal` as currency: check **Currency** and set the decimal places

**Field `Component` (relationship)**

In the relationship, you configure:

* the **related component**
* if it is **1-N** or **N-N** (multiple values)
* which field of the related is the **Display Field**
* the flag **deleteCascade**

`deleteCascade` defines whether, when removing a “parent” record, the system removes relations in cascade.

Example:

* `ServiceOrder`
* `ServiceOrderItem` with a field `serviceOrder` (type `Component`)
* with `deleteCascade = true`, when deleting the SO, deletes the related items

{% hint style="danger" %}
Use `deleteCascade` be careful. It can delete data in bulk.
{% endhint %}

**Queries**

You can **add, edit and remove** queries on the component table. Use to standardize filters and reuse listings.

#### Scripts (Python)

You can **add, edit and remove** Python scripts. Use for backend business rules, tied to component events.

#### Dashboards and reports

You can **add, edit and remove** reports and dashboards in the visual editor.

<details>

<summary>Visual editor training</summary>

Video content (coming soon).

</details>

### Frontend (generated structure)

When you check **Create frontend files**, Madrix creates the base frontend structure. It works as a scaffold for screens, routes and theme.

<details>

<summary>Folder structure (summary)</summary>

* Public folder
  * `favicon.ico`
* Private folder
  * `components/`
    * `background/` (`background.tsx`, `classes.ts`, `index.ts`)
    * `forms/`
      * `{{component_name_form.tsx}}` (one form per component)
  * `layouts/`
  * `pages/`
    * `protected/`
      * `Home/`
      * `{module}/`
        * `components/` (create/edit/list screens)
        * `kanban-view/`
        * `reports/`
    * `public/`
      * `login/index.tsx`
  * `routes/`
  * `schemas/`
  * `settings/`
  * `theme/`
  * `app.tsx`
  * `global-config.ts`
  * `global.css`
  * `main.tsx`
  * `vite-env.d.ts`
  * `sads/`
* Files at the root
  * `bun.lock`
  * `index.html`
  * `vercel.json`
  * Files marked as **locked** (do not edit):
    * `bunfig.toml`
    * `package.json`
    * `tsconfig.json`
    * `tsconfig.node.json`
    * `vite.config.ts`

</details>

{% hint style="info" %}
File **locked** is managed by the platform.&#x20;
{% endhint %}

### Talk about Updating Madrix Core


# Project Settings

Here you configure your project's identity, access, and deployment.

For security, authentication, and policies of the running app, use [Runtime Settings](/documentation/runtime-settings).

### Basic Settings

You can adjust:

* **Project name (Display Name** per languag&#x65;**)**
* **Delete the project**

{% hint style="danger" %}
**Danger Zone: remove project**\
This action is irreversible.\
It removes project data, components, menus, and settings.

To confirm, type the **project name** and click **Confirm deletion**.
{% endhint %}

### Visual identity

Use to align the app with your brand.

Common settings:

* **Project icon**
* **Dark Mode**
* **Contrast**
* **Right to Left (RTL)**
* **Compact**
* **Layout**
  * Left menu
  * Top menu
  * Collapsed left menu
* **Font**
  * Font type
  * Font size
* **Theme colors**
  * Primary
  * Secondary
  * Info
  * Success
  * Warning
  * Error

Finish with **Save** or discard with **Cancel**.

### Languages

Here you manage the languages enabled in the project.

You can:

* See the list of configured languages.
* Add a language.
* Remove a language.

### Project team

Use to share the project with other people on the platform.

Each member can have a different role (e.g., administrator).

### GitHub

Connect a repository to synchronize code and history.

Common fields:

* **Repository URL**
* **Branch**
* **Access Token**
* **Auto-sync enabled**

Typical flow:

1. Fill in URL, branch, and token.
2. Click **Test connection**.
3. Click **Connect**.

{% hint style="warning" %}
Use a token with the smallest possible scope.\
Avoid personal tokens shared between people.
{% endhint %}

### Version history

Here you see the project's version stack.

You can:

* Identify the **current version**.
* Run a specific version.
* Revert to a previous version.

{% hint style="warning" %}
Reverting can undo UI changes and rules.\
Test in Preview before publishing to production.
{% endhint %}

### Cloud environments

A Cloud environment is where your app is published.

Examples:

* `Dev` for quick tests.
* `Staging` for acceptance testing.
* `Prod` for end users.

#### Create and publish an environment (recommended flow)

{% stepper %}
{% step %}

### Create the environment

In the environments list, click **Add**.

Fill in:

* **Environment name**
* **External domain** (optional)
* **Application server**
* **Database server**
* **File storage**

Click **Proceed to payment** or **Cancel**.
{% endstep %}

{% step %}

### Payment (Stripe)

Payment is processed securely via Stripe.

When you proceed, you will see the checkout screen.
{% endstep %}

{% step %}

### Provisioning (Not Ready → Ready)

After payment, the environment remains **Not Ready** while provisioning.

Wait about **5 minutes**.
{% endstep %}

{% step %}

### Publish

When it is ready, the status changes to **Ready**.

If you click **Publish** before that, the indicator turns red.

![](/files/be845ff0b09550b52f5733991b2905132d017b40)

When the environment is ready, it appears in green.

<figure><img src="/files/2cd668fe4eef4d08a99ecaa5635865a2c2df97be" alt=""><figcaption><p>Status ready to publish</p></figcaption></figure>

Select the environment and click **Publish**.
{% endstep %}

{% step %}

### Wait and access

After publishing, wait about **3 minutes**.

Access the app via the environment URL.

In the list, it should appear as **Ready**.

<figure><img src="/files/85aba048ebe5e6311a1a859ba0ee5e65facec8d0" alt=""><figcaption><p>Published environment</p></figcaption></figure>
{% endstep %}
{% endstepper %}

#### Edit an environment

To change settings, click the environment's gear.

{% hint style="info" %}
Environments are provisioned on AWS with IaC, containers, load balancing, auto-scaling, and high availability Multi-AZ.
{% endhint %}

### Next steps

* Fine-tuning backend and scaffold: [Editor Mode](/documentation/editor-mode)
* Product overview: [Platform](/documentation/platform)
* Connections to your stack: [Integrations](/documentation/integrations-and-api)


# Runtime Settings

Here you configure **security, authentication and access** of the running app.

For visual identity, deploy and GitHub, use [Project Settings](/documentation/project-settings).

{% hint style="warning" %}
The defaults below are of **the highest possible strictness**.\
They increase friction and require a well-defined support process.
{% endhint %}

### Overview (what you control here)

You typically configure:

* **SSO (SAML/OIDC) + Entra ID**
* **Access profiles (RBAC)** and **permissions**
* **Users**
* **Security policies** (password, 2FA, session, lockout, IP allowlist)
* **Audit and trails**
* **Email server** (invites, reset, alerts)
* **Logs** and **encryption**
* **Governance** (LGPD/GDPR)

### Authentication (SSO: SAML/OIDC + Entra ID)

Higher-strictness recommendation:

* **SSO required** for all users.
* **Disable local login** (password) when SSO is stable.
* **Enforced MFA at the IdP** (e.g.: Entra ID Conditional Access).
* **Restrict by domain** (only approved corporate emails).

Deployment checklist:

* Set the provider: **SAML** or **OIDC**.
* Configure URLs, issuer/client, certificates and claims.
* Map claim to **email** (identity) and **groups** (authorization).
* Validate logout **scenario** and session expiration.

{% hint style="danger" %}
Enable SSO first in a test environment.\
A misconfiguration can prevent everyone from logging in.
{% endhint %}

If it locks login or callback: [SSO and login](/troubleshooting/sso-and-login).

### Users and profiles (RBAC)

#### Access profiles

Use profiles to group permissions by role.

Minimum fields:

* **Name**
* **Description**

Best practices (high strictness):

* Create small and explicit profiles (e.g.: `Finance: Read`, `Finance: Operate`).
* Avoid “Administrator” profiles for daily use.
* Use a **Break-glass admin** (emergency) with governance.

#### Users

Minimum fields:

* **Name**
* **Email**
* **Access profiles**

Best practices (high strictness):

* Disable self-service registration if it exists.
* Use email invitation with short expiration.
* Remove access for offboarding on the same day.

### Permissions (high strictness)

Recommended default:

* **Deny-by-default** (everything denied, allow as needed).
* Permissions by:
  * module
  * component/entity
  * action (view/create/edit/delete/export)

{% hint style="info" %}
Separate “view data” from “export data”.\
Export is one of the biggest leak vectors.
{% endhint %}

### Audit and trails

Enable auditing for security events and sensitive data.

Minimum trail fields:

* **User**
* **Action**
* **Resource**
* **Date/Time**
* **IP**
* **Status**

Minimum events (high strictness):

* login/logout
* login failures and lockouts
* password reset/change
* changes in SSO and security policies
* profile/permission changes
* data export

Recommended retention:

* **365 days** (minimum)
* **2–7 years** if there is a regulatory requirement

### Email server

Use for:

* invitations
* password reset (if local login is enabled)
* security alerts (e.g.: lockout, new device)

Recommendation (high strictness):

* Use corporate domain and SPF/DKIM/DMARC.
* Avoid providers without reputation and without logs.

### Security policies (high strictness)

#### Password policy (when local login exists)

Recommended values:

* **Minimum Length**: `14` (preferably `16`)
* **Require uppercase**: `on`
* **Require lowercase**: `on`
* **Require numbers**: `on`
* **Require special characters**: `on`
* **Prevent reuse**: `24`
* **Expiration**: `90` days (if your policy requires)

{% hint style="warning" %}
Password expiration increases support calls.\
If you use SSO + strong MFA, prefer expiration at the IdP.
{% endhint %}

#### Two-Factor Authentication (2FA)

Recommended values:

* **Enabled**: `on`
* **Mandatory for all**: `on`
* **Available methods**:
  * **TOTP/Authenticator** (preferred)
  * Email only as fallback (if allowed)

#### Session management

Recommended values:

* **Inactivity timeout**: `15` minutes
* **Absolute session timeout**: `8` hours
* **Max concurrent sessions**: `1`
* **Allow "Remember Me"**: `off`

{% hint style="info" %}
Single session reduces the risk of session hijacking.\
It also reduces “account sharing”.
{% endhint %}

#### Login attempts (lockout)

Recommended values:

* **Max attempts**: `5`
* **Lockout duration**: `30` minutes

Extra recommendation (if supported):

* Progressive lockout (e.g.: 5 failures = 30 min, 10 failures = 24 h).

#### IP allowlist (allow only approved networks)

Recommended values:

* **Enabled**: `on` (in production)
* Register corporate networks and IPs.

Examples:

* `192.168.1.0/24`
* `10.0.0.0/8`
* `203.0.113.10/32`

{% hint style="danger" %}
IP allowlist is easy to get wrong.\
Maintain an emergency path (VPN + fixed IP + break-glass account).
{% endhint %}

### Logs

Recommendation (high strictness):

* Security logs separate from application logs.
* Never log: passwords, tokens, secrets, sensitive data.
* Alert on critical events (e.g.: many login failures, permission change).

### Encryption (in transit and at rest)

Recommendation (high strictness):

* **In transit**: TLS 1.2+ required.
* **At rest**:
  * database with encryption at rest
  * attachments/files with encryption at rest

### LGPD/GDPR and data governance

Minimum points to operate with rigor:

* Role-based access control (RBAC) and least privilege principle.
* Trails for access and export of personal data.
* Retention policy by data type.
* Process for:
  * responding to data subject requests (when applicable)
  * removal/anonymization (when applicable)


# Integrations and API

Connect your app to external systems securely and predictably.

Use this page as **decision guide + checklist**. Then, detail per case.

{% hint style="info" %}
Integrations almost always touch authentication and governance. Combine with [Runtime Settings](/documentation/runtime-settings).
{% endhint %}

### Quick decisions (before implementing)

1. **Direction:** Inbound (incoming) or Outbound (outgoing)?
2. **Mode:** synchronous (API) or asynchronous (events/webhook/queue)?
3. **Frequency:** real-time, near real-time, or batch?
4. **Contract:** do you control both sides (better) or is it a “third-party API”?
5. **Reliability:** need retries, reprocessing, idempotency?

### Minimum checklist (production)

* **Environments:** endpoints and credentials per Dev/Staging/Prod.
* **Authorization:** least privilege (minimal scopes/roles).
* **Secret rotation:** with date and owner.
* **Observability:** logs + correlation (e.g.: `requestId`, `eventId`).
* **Failure handling:** retry with backoff + dead-letter/reprocess.
* **LGPD:** avoid leaking PII in logs and payloads.

### API Authentication (OAuth2/OIDC, tokens)

Choose a standard and document it. Avoid “fixed token” without rotation.

#### Common options

* **OAuth2 Client Credentials:** good for system-to-system integration.
* **OAuth2 Authorization Code (with PKCE):** good when there's a user.
* **OIDC (ID token):** for identity; does not replace API authorization.
* **API keys / personal tokens:** only if rotation and scope exist.

#### Practical rules

* Validate **audience**, **issuer** and token expiration.
* Separate “who authenticated” from “what they can do” (claims vs roles).
* Standardize error response:
  * `401`: not authenticated / invalid/expired token.
  * `403`: authenticated, but without permission.

{% hint style="warning" %}
If you use corporate SSO, validate claims and group mapping. See [SSO and login](/troubleshooting/sso-and-login).
{% endhint %}

### Rate limits and quotas

Rate limit is part of the contract. Document limit and retry behavior.

#### Client best practices

* Treat `429 Too Many Requests` as expected.
* Respect `Retry-After` when present.
* Use **exponential backoff** with jitter.
* Controlled parallelism. Avoid “fan-out” without limit.

#### How to design limits (server side)

* Limit by **tenant** + by **credential** (service account).
* Differentiate **burst** vs **sustained**.
* Protect expensive endpoints (search, reports, exports).

### Webhooks

Webhooks are the simplest way to be “event-driven” when you don't control queues.

#### Webhook checklist (sender)

* Versioned payload (`schemaVersion`).
* `eventId` single + `occurredAt`.
* Automatic retry with backoff.
* Payload signature (e.g.: HMAC) + secret rotation.

#### Webhook checklist (receiver)

* Respond `2xx` quickly. Process asynchronously.
* Implement **idempotency** by `eventId`.
* Log: status, attempts, last error, processing time.
* Have a button/route to **reprocess** for events with errors.

<details>

<summary>Specification template (copy and paste)</summary>

```
Webhook: {{name}}

Events:
- {{event1}}
- {{event2}}

Contract:
- eventId: string (unique)
- occurredAt: ISO-8601
- type: string (event name)
- payload: object (versioned schema)

Reliability:
- Retry: yes, with backoff
- Idempotency: by eventId
- Receiver timeout: {{N}}s

Security:
- Signature: HMAC-SHA256
- Signature header: {{headerName}}
- Secret rotation: every {{N}} days
```

</details>

### Connectors (ERP/CRM/…)

A connector is an integration package with:

* Authentication + credential renewal.
* Object mapping (e.g.: `Customer` ↔ `Account`).
* Synchronization (push, pull, or both).
* Error handling and reprocessing.

#### Sync strategies (choose 1)

* **Pull (polling):** simple, but increases cost and latency.
* **Push (webhook/event):** better for real-time.
* **Hybrid:** webhook + daily reconcile (reduces “drift”).

{% hint style="info" %}
If you need to “integrate fast”, start with hybrid. Webhooks fail. Reconciliation saves.
{% endhint %}

### Integration with database / data access

Direct integration via database is powerful, but risky.

#### Guardrails

* Prefer **read** (views/read replica) instead of direct write.
* Define schema owner. Avoid “app writing to ERP schema”.
* Do not couple to volatile internal tables. Prefer stable views.
* Log slow queries. Create indexes carefully.

### How to request this in Madrix (prompts)

If you will generate/adjust integration via Chat AI, provide testable requirements.

{% hint style="success" %}
For a ready prompt for integration with log + reprocess, see the block **Integrations** in [Quick prompts](/hands-on-tutorials/2.-quick-prompts).
{% endhint %}

<details>

<summary>Base prompt — integration via webhook (copy and paste)</summary>

```
Implement a webhook for the event {{event}}.

Requirements:
- Endpoint configurable per environment (Dev/Staging/Prod).
- Log payload, status, attempts and errors.
- Idempotency by eventId.
- Allow reprocessing events with errors (Admin only).
- Do not expose sensitive data in logs.
```

</details>

### Quick troubleshooting

* **401/403 in integration:** token expired? scopes/roles correct?
* **429:** high parallelism? missing backoff? is there batch?
* **Webhook duplicating:** missing idempotency by `eventId`.
* **“Slow” integration:** external call blocking main request? See [Performance and slowness](/troubleshooting/performance-and-slowness).


# Plans and Pricing

Use this page to compare limits and operating options.

{% hint style="info" %}
For deployment and operation, combine with: [3. Deployment and Cloud Environments](/hands-on-tutorials/3.-deployment-and-cloud-environments) and [Runtime Settings](/documentation/runtime-settings).
{% endhint %}

### Comparison

<table data-full-width="false"><thead><tr><th width="339.39996337890625">Item</th><th>Free</th><th>Enterprise</th><th>Full</th></tr></thead><tbody><tr><td><strong>BUILD</strong></td><td></td><td></td><td></td></tr><tr><td>  Projects</td><td>Unlimited</td><td>Unlimited</td><td>Unlimited</td></tr><tr><td>  AWU Credits</td><td>120</td><td>1500/month</td><td>Custom</td></tr><tr><td><strong>DEPLOY</strong></td><td></td><td></td><td></td></tr><tr><td>  Madrix Cloud Shared (AWS)</td><td>No</td><td>Yes</td><td>Yes</td></tr><tr><td>  Madrix Cloud Dedicated (AWS)</td><td>No</td><td>Yes</td><td>Yes</td></tr><tr><td>  Private cloud</td><td>No</td><td>No</td><td>Yes</td></tr><tr><td>  On-premise (Kubernetes)</td><td>No</td><td>No</td><td>Yes</td></tr><tr><td><strong>RUN</strong></td><td></td><td></td><td></td></tr><tr><td>  Database tenancy</td><td>Shared</td><td>Dedicated</td><td>Dedicated</td></tr><tr><td>  End users</td><td>Unlimited</td><td>Unlimited</td><td>Unlimited</td></tr><tr><td>  Vertical scalability</td><td>No</td><td>Yes</td><td>Yes</td></tr><tr><td>  Horizontal scalability</td><td>No</td><td>Yes</td><td>Yes</td></tr><tr><td>  High availability (auto-failover)</td><td>No</td><td>No</td><td>Yes</td></tr><tr><td>  Cross-regional failover</td><td>No</td><td>No</td><td>Yes</td></tr><tr><td><strong>SUPPORT</strong></td><td></td><td></td><td></td></tr><tr><td>  AI Assistant</td><td>Yes</td><td>Yes</td><td>Yes</td></tr><tr><td>  Customer Success Manager (8x5)</td><td>No</td><td>Yes</td><td>Yes</td></tr><tr><td>  Customer Success Manager (24x7)</td><td>No</td><td>No</td><td>Yes</td></tr><tr><td>  Uptime guarantee</td><td>99.5%</td><td>99.95%</td><td>99.95%</td></tr></tbody></table>

### What AWUs are

AWUs (Agentic Work Units) are monthly credits for agentic building with Madrix. Each AWU includes model tokens, agent processing, and storage/logs. Use AWUs to create, tune, and validate your apps.

### Deployment and operation (overview)

These options come into play in environment design. They are available in all plans. They may depend on architecture, region, and security requirements.

#### Deployment options

* **Madrix Cloud (AWS):** dedicated environment per organization.
* **Private cloud:** deployment in the customer's account/infrastructure.
* **On-premise:** running in your datacenter (Kubernetes).

#### Run capabilities (when applicable)

* Vertical and horizontal scalability.
* High availability (auto-failover).
* Cross-regional failover.

#### Support (when applicable)

* Customer Success Manager (8x5).
* Customer Success Manager (24x7).

###


# Troubleshooting

Solve common problems by symptom. Follow the quick checklist first.

### Quick checklist (2 min)

1. Reload the page and try again.
2. Test in an incognito window (no extensions).
3. Disable adblock/privacy extensions for the domain.
4. Confirm permissions and the correct environment (Dev/Staging/Prod).

### Choose the topic

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td><strong>AI generation failures</strong><br>Generation doesn't start, freezes, or delivers inconsistent results.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/c88ccfc4e3b96fb8e894224a3798848537296cfe">/spaces/jLpkUQEEJ5BcMqj70lza/pages/c88ccfc4e3b96fb8e894224a3798848537296cfe</a></td></tr><tr><td><strong>Deployment issues</strong><br>Deployment failing, stuck, or app down after publishing.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/da80cd1d946a058845c6d629b7458fe3ac0e8742">/spaces/jLpkUQEEJ5BcMqj70lza/pages/da80cd1d946a058845c6d629b7458fe3ac0e8742</a></td></tr><tr><td><strong>SSO and login</strong><br>Login looping, callback error, or access denied after authenticating.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/1ead91f77b7b43b0f7bacbc9ede8cb58df53aa44">/spaces/jLpkUQEEJ5BcMqj70lza/pages/1ead91f77b7b43b0f7bacbc9ede8cb58df53aa44</a></td></tr><tr><td><strong>Performance and slowness</strong><br>Slow UI, slow endpoints, or timeouts.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/ffd4c1d6ca45e6646842549bd4c4a80b2c79f809">/spaces/jLpkUQEEJ5BcMqj70lza/pages/ffd4c1d6ca45e6646842549bd4c4a80b2c79f809</a></td></tr><tr><td><strong>Database, migrations and schema</strong><br>Migration fails, divergent schema, or connection error.</td><td><a href="/spaces/jLpkUQEEJ5BcMqj70lza/pages/6192c43368d5befb9c7421a950dadb3110d7ff22">/spaces/jLpkUQEEJ5BcMqj70lza/pages/6192c43368d5befb9c7421a950dadb3110d7ff22</a></td></tr></tbody></table>

### How to escalate (open a ticket)

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# AI generation failures

When generation doesn't start, freezes, or delivers inconsistent results.

### When to use

* Generation does not start after sending the prompt.
* Generation keeps “running” for a long time.
* The result comes back incomplete or inconsistent with the prompt.

### Quick checklist (2 min)

1. Simplify the prompt. Make a minimal version.
2. Generate again. Avoid multiple parallel submissions.
3. Reload the page. Try an incognito window.
4. Disable adblock/privacy extensions for the domain.

### Diagnosis

#### 1) Is what you asked for “executable”?

* The prompt has **goal**, **modules/entities**, and **minimal screens**.
* Avoid ambiguity: “a complete system” without scope explodes cost and time.

#### 2) Is the error network/UI related?

* Open the browser Console.
* Check if there is a failing request (401/403/429/5xx).

#### 3) Is the error capacity/limit related?

* If there is a “rate limit”, wait a few minutes and try again.
* Avoid giant prompts. Break them into steps.

### How to resolve (patterns)

* **Gets stuck halfway**: reduce the scope and generate in increments.
* **Poor specification**: force structure with sections and bullets.
* **Result missing parts**: ask for only 1 thing at a time (“add X”, then “adjust Y”).

### When to escalate

* The same minimal prompt fails 3 times.
* Repeatable 5xx error.
* Generation completes, but the app does not run even in Preview.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# Deploy issues

Deploy failing, stuck, or app down after publishing.

### When to use

* Deploy fails with error.
* Deploy is in progress and doesn't finish.
* Deploy completes, but the application doesn't start.

### Quick checklist (2 min)

1. Confirm the correct environment (Dev/Staging/Prod).
2. Run a new deploy. Avoid 'deploy spam'.
3. Check if there was a recent change to variables/secrets.

### Diagnosis

#### 1) Is the error build or runtime?

* **Build**: fails before publishing artifacts.
* **Runtime**: publishes, but crashes on startup or at endpoints.

#### 2) Environment configuration

* Are required variables set?
* Do integrations (API keys) exist in the correct environment?

#### 3) External dependencies

* Is the database accessible?
* Do webhooks and third-party services respond?

### How to resolve (patterns)

* **Build broke**: review recent changes and revert the last delta.
* **Runtime crashed**: check app logs and startup failure.
* **Intermittent error**: confirm limits (rate limit), timeout, and dependencies.

### When to escalate

* 5xx error in the pipeline is repeatable.
* Deploy stuck for more than 20 min.
* App with downtime in Staging/Prod.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# SSO and login

SSO, login loop, callback error, or expired session.

### When to use

* Looping login.
* SSO returns error after authenticating at the IdP.
* User authenticates but does not have access to the project.

### Quick checklist (2 min)

1. Test in an incognito/private window.
2. Clear cookies for the domain.
3. Confirm the user is in the correct tenant/organization.

### Diagnosis

#### 1) Permissions vs authentication

* **Authenticated** but does not see resources: usually permission/group related.
* **Not authenticated**: usually SSO/callback configuration.

#### 2) Callback and redirect URI

* Confirm if the `redirect/callback URL` from the IdP matches exactly what is configured.
* Check for differences in http/https or domain.

#### 3) Clock skew and expiration

* Do tokens expire quickly?
* Do errors vary by user/machine?

### How to resolve (patterns)

* **Loop**: clear cookies and review domain/callback.
* **403 after login**: adjust groups/roles and claim mapping.
* **Error only in one browser**: extension blocking cookies/3rd-party.

### When to escalate

* All users in an org fail.
* Reproducible callback error.
* Recent change in IdP (certificate/metadata) causing widespread breakage.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# Performance and slowness

Slow UI, slow endpoints, timeouts, or high consumption.

### When to use

* UI slow to load lists and forms.
* API timeouts.
* Slowness only in one environment (e.g., Prod).

### Quick checklist (2 min)

1. Compare Dev vs Staging vs Prod.
2. Test with a “clean” user (without much data).
3. Isolate: is it UI, API, or database?

### Diagnosis

#### 1) Is it client-side or server-side?

* Client-side: high CPU in the browser, heavy rendering.
* Server-side: slow requests in Network, high time-to-first-byte.

#### 2) Data and queries

* Lists without pagination tend to degrade quickly.
* Filters and sorts may require indexes.

#### 3) Integrations

* Do calls to external services block the main request?
* Are timeouts configured?

### How to resolve (patterns)

* **Slow lists**: pagination, mandatory filters, reduce columns.
* **Slow API**: review critical endpoints and queries.
* **Database**: indexes, avoid N+1, review recent migrations.

### When to escalate

* SLA affected in Staging/Prod.
* Abrupt degradation after release.
* Frequent and repeatable timeouts.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# Database, migrations and schema

Migrations failing, divergent schema, or connection errors.

### When to use

* Migration fails on deploy.
* App starts, but gives error of non-existent table/column.
* Database connection errors.

### Quick checklist (2 min)

1. Confirm in which environment the error occurs.
2. Check the most recently applied migration.
3. See if there is a mismatch between expected schema and actual schema.

### Diagnosis

#### 1) Connection

* Correct credentials/URL?
* Network/VPC open (if applicable)?

#### 2) Order and idempotence of migrations

* Does a migration depend on another that didn't run?
* Does a migration run twice and break?

#### 3) Existing data

* Altering a column with old data often breaks.
* Constraints (NOT NULL / FK) require backfill.

### How to resolve (patterns)

* **Column/table error**: review the last migration and the schema.
* **Constraint failed**: perform backfill before applying constraint.
* **Connection**: validate secrets and network permissions.

### When to escalate

* Migration repeatedly breaks in the pipeline.
* Corruption/inconsistent data.
* Error only in Prod and not reproducible in Staging.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}


# Release Notes

## Release Notes

Product changes, in chronological order. Focus on impact and action.

### What to record here

* **Added:** new features and new capabilities.
* **Improved:** performance, UX, quality, limits, coverage.
* **Fixed:** bugs and regressions.
* **Breaking change (if any):** what broke + how to migrate.

{% hint style="info" %}
A good release note answers: **what changed**, **for whom**, **what impact**, **what to do now**.
{% endhint %}

### Template (copy and paste)

<details>

<summary>Update template</summary>

{% code title="Template" %}

```
{% update date="YYYY-MM-DD" %}
# YYYY-MM-DD — Short release title

## Added
- _(what was added + for whom)_

## Improved
- _(what improved + measurable impact, if any)_

## Fixed
- _(what was fixed + context of the problem)_

## Breaking changes (if any)
- _(what changed)_
  - **How to migrate:** _(short steps)_
  - **Who is affected:** _(e.g.: production projects / only new ones)_
{% endupdate %}
```

{% endcode %}

</details>

{% updates format="full" %}
{% update date="2026-02-21" %}

## 2026-02-21 — (fill in the release title)

### Added

* *(fill in)*

### Improved

* *(fill in)*

### Fixed

* *(fill in)*

### Breaking changes (if any)

* *(fill in)*

{% hint style="warning" %}
If there is a change that affects production, put it at the top and include “How to migrate”.
{% endhint %}
{% endupdate %}
{% endupdates %}


# Roadmap

### Overview

Here are the upcoming evolutions of Madrix. Use this roadmap to plan adoption and internal releases.

{% hint style="info" %}
Roadmap is intent. Scope and order may change. What has been delivered goes into [Release Notes](/release-notes).
{% endhint %}

### Status

* **Now**: in progress. Delivery in the coming weeks.
* **Next**: prioritized. Will enter execution next.
* **Later**: direction. Depends on validation and capacity.
* **Under research**: validated problem. Solution still being designed.

## Now (next weeks)

#### Deploy and Cloud

* UX improvements in the flow of **Cloud Environments**.
* More clarity in pipeline errors (build vs runtime).
* Better post-deploy health-checks.

#### AI Chat Mode

* More predictable prompts for incremental changes.
* Better “mental diff” of what will be changed before approving.
* Safer re-execution in case of intermittent failure.

#### Quality and performance

* Reduction of loading times in Preview.
* Stability improvements during usage peaks.

##

## Next (30–60 days)

#### Editor Mode

* Faster navigation between modules, entities and UI.
* Improvements in editing rules and permissions.
* Earlier validations to avoid deploying with an obvious error.

#### Observability

* Logs more accessible by environment (Dev/Staging/Prod).
* Deploy events with clearer history.

#### Integrations

* Improvement in managing keys and secrets per environment.
* Simpler UX to connect common providers.

##

## Later (60–120 days)

#### Security and access

* Finer permission policies by module/entity.
* Evolutions in SSO and governance (as requested).

#### Platforms and extensibility

* More extension points for advanced customizations.
* Better support for enterprise standards (audit and compliance).

## Under research

* Ephemeral environments per branch/release.
* Faster and more controlled rollback in Prod.
* More opinionated project templates by industry.

## How to request a feature

When suggesting something, send:

1. **Goal** (what you need to achieve).
2. **Who uses** (profile and volume).
3. **Current flow** (where it hurts today).
4. **Definition of done** (how you will validate).

{% hint style="success" %}
The clearer the “definition of done”, the faster it gets prioritized.
{% endhint %}

***


# Affiliate Program

Make acquisition and conversion easier with simple, copyable, scalable content. Earn commissions by promoting Madrix.

Promote Madrix with trackable links and ready-made content. You earn a commission for customers attributed to your link.

{% hint style="success" %}
**Commission:** 10% on eligible payments from the customer attributed.\
**Duration:** 12 months per attributed customer.\
**Tracking:** via Affiliate Dashboard.
{% endhint %}

### Who it's for

* Content creators (LinkedIn, YouTube, newsletter).
* Consultants and freelancers (dev, product, data, automation).
* Agencies that recommend tools in delivery.

### Quick checklist

{% stepper %}
{% step %}

### Activate your affiliate access

* [ ] Create your account and log in.
* [ ] Request access to the **Affiliate Program** (may require approval).
* [ ] Confirm that you can see the **Affiliate Dashboard**.

**Expected result:** you can see clicks and conversions in the dashboard.
{% endstep %}

{% step %}

### Generate your affiliate link (with UTM)

* [ ] Use one link per channel (LinkedIn, YouTube, newsletter).
* [ ] Standardize UTMs to compare performance.
* [ ] Test the link in an incognito tab before publishing.

Recommended standard:

* `utm_source=linkedin`
* `utm_medium=post`
* `utm_campaign=affiliates`
* `utm_content=demo-7min`

Example URL (template):

`https://YOUR-LINK-HERE?utm_source=linkedin&utm_medium=post&utm_campaign=affiliates&utm_content=demo-7min`

**Expected result:** you can separate results by channel and format.
{% endstep %}

{% step %}

### Publish 1 piece of content per day for 7 days

* [ ] Vary the format: short post, 60s video, thread, email.
* [ ] Repurpose the templates below.
* [ ] Use a single CTA per piece of content.
* [ ] Monitor clicks, sign-ups and conversions in the dashboard.

**Expected result:** you discover 1 channel with good traction.
{% endstep %}
{% endstepper %}

### How it works

#### Commission structure

* Commission per customer attributed to your link.
* Standard commission: **10%**.
* Standard duration: **12 months** per attributed customer.
* Final rules may vary by plan and campaign.

#### Tracking and attribution

Validate these points in the dashboard before promoting:

* **Attribution window (cookie):** how many days after the click count.
* **Attribution model:** usually last-click.
* **Tracked events:** click, sign-up, upgrade and payment.

#### What each metric means

Use these definitions to align expectations with your audience.

* **Click:** someone opened your trackable link.
* **Sign-up:** created an account after visiting via your link.
* **Activation:** completed a minimal action in the product.
* **Conversion:** became a paying customer.
* **Approved for payout:** passed validation and was not refunded.

#### Affiliate dashboard

The dashboard usually answers these questions:

* How many clicks did I generate per channel?
* How many sign-ups and activations came from my link?
* Which customers are pending validation?
* What amount is approved for payout?

#### Payments and reports

Confirm in the dashboard (or in the terms) before planning your schedule:

* Payout frequency (monthly / biweekly).
* Minimum amount for payment.
* Method (e.g. transfer) and required details.
* Refund/chargeback rules and validation period.

### Recommended links

Use one landing per intent. Avoid mixing CTAs.

* For “hands-on”: [Start here](/get-started-here)
* For “see it live”: [Demonstrations](/demonstrations)
* For “first deploy”: [Deploy and Cloud Environments](/hands-on-tutorials/3.-deployment-and-cloud-environments)

### Marketing kit

#### Ready copies (copy and paste)

{% tabs %}
{% tab title="LinkedIn (short)" %}
If you want to get software out of the idea phase faster:

I used Madrix to go from **prompt → app** in minutes. It helps create, iterate and publish with more control and governance.

Want to see a 7-min demo? Message me or click the link.
{% endtab %}

{% tab title="WhatsApp (direct)" %}
I tried Madrix: you can go from prompt → app pretty fast.

If it makes sense, I’ll send you a 3–7 min demo + link.
{% endtab %}

{% tab title="Email (B2B)" %}
Subject: Quick demo: prompt → app in minutes

Hi {Name},

If you are evaluating how to accelerate delivery with AI, it's worth checking out Madrix. In a few minutes you can create a simple app and publish an environment.

If you’re up for it, I’ll send a short demo and the link to try it.
{% endtab %}
{% endtabs %}

#### Quick hooks (to vary the start of the post)

* “If you’ve tried ‘AI that generates apps’ and got frustrated…”
* “The problem isn’t generating code. It’s governing changes.”
* “You can go from prompt to app without losing control.”
* “What changed when I tested building with agents?”
* “Quick demo: what you can do in 7 minutes.”

#### Assets and formats

* **Banners and images:** use for posts and landing pages.
* **Short videos (30–60s):** better for click volume.
* **Screen capture (2–5 min):** better for conversion.

#### Recommended landing pages

Always use one landing per intent:

* **“See quick demo”** (top of funnel)
* **“Create first project”** (hands-on)
* **“Governance and enterprise”** (decision-maker)

#### Template library

* Post templates (educational, case study, comparative).
* Library of hooks and headlines.
* Post calendar (4 weeks).

### Quick demo script

Use this script for short, repeatable demos.

#### 7-min version (recommended)

* **1 min:** what Madrix is and who it's for.
* **3 min:** create a live system (prompt → generate).
* **2 min:** make 1 quick change (Chat AI vs Editor).
* **1 min:** deploy to a cloud environment (overview).

#### Script (suggested lines)

* “I will create an app from scratch with a prompt.”
* “Now I will approve the specification and generate the software.”
* “I will request a change and show where it appears in the project.”
* “Finally, I will publish to the cloud to make it accessible.”

#### Common objections (short answers)

* **“Is this just another ‘generator’?”** No. It's a build + iteration + deploy flow.
* **“Can it be governed?”** That's a focus. Validate the control options in your case.
* **“What about maintenance?”** Treat it like a software project. Use incremental iteration.

### Light educational content

Content ideas that convert without sounding like “advertising”.

* What is an **agentic software platform** (in practical terms).
* Why **governance** matters when AI generates software.
* Main use cases (by area and by maturity).
* Benefits vs. traditional tools (where it wins and where it doesn’t).
* How to talk about ROI without making up numbers (time, risk, cost).

### Videos for affiliates (30s-5 min)

Video suggestions (titles and formats):

* **Madrix in 60 seconds** (teaser)
* **Build an app in 3 minutes** (screen capture)
* **Top 5 use cases Madrix solves** (list)
* **Why enterprises need governance with AI** (educational)
* **How to pitch Madrix (affiliate version)** (script)

#### Materials

* Links with UTMs ready per channel.
* Post calendar (4 weeks).
* Library of hooks and headlines.
* Email templates.

### Rules and policies (summary)

Use as a guardrail. The program terms are the final rule.

#### You may

* Use UTMs per channel and per format.
* Talk about qualitative and observable results.
* Indicate the full flow (prompt → generate → iterate → deploy).

#### You may not

* Spam (mass DMs, purchased lists, aggressive automation).
* Promises without basis (“guaranteed ROI”, “replaces your team”).
* Use of brand/identity outside the official kit, if any.
* Paid media with brand bidding, if the terms prohibit it.

### Next steps

* Publish 3 pieces of content and compare performance by UTM.
* Repurpose what performs: same theme, new format.
* Drive traffic to a single CTA per post.