# 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](/documentation/chat-ai-mode.md)
* Advanced settings (backend + scaffold): [Editor Mode](/documentation/editor-mode.md)
* Project settings: [Project Settings](/documentation/project-settings.md)
* Runtime settings (security, auth, etc): [Runtime Settings](/documentation/runtime-settings.md)
* Connect with your stack: [Integrations](/documentation/integrations-and-api.md)

### 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.md).
{% 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.md)

#### 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.md)

### 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.md)
* Want to see real cases: [Demonstrations](/demonstrations.md)
* Stuck on something: [Troubleshooting](/troubleshooting.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.madrix.dev/documentation/platform.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.