# Platform

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](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/modo-chat-ai)
* Advanced settings (backend + scaffold): [Editor Mode](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/modo-editor)
* Project settings: [Project Settings](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/configuracoes-do-projeto)
* Runtime settings (security, auth, etc): [Runtime Settings](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/configuracoes-do-runtime)
* Connect with your stack: [Integrations](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/integracoes-e-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](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/comece-aqui).
{% 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](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/modo-chat-ai)

#### 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](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/documentacao/modo-editor)

### 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](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/tutoriais-praticos)
* Want to see real cases: [Demonstrations](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/demonstracoes)
* Stuck on something: [Troubleshooting](https://app.gitbook.com/s/XnYvLewhXbdSQIvAlbqN/solucao-de-problemas)