Conceptos

Mentat encarna una ontología operacional al estilo Palantir Foundry: modelás el negocio como objetos tipados, los relacionás, y definís acciones ejecutables y auditadas sobre ellos. Todo lo demás de la plataforma habla este mismo idioma.

Estos son los seis conceptos centrales y cómo se relacionan.

OntologyType — la clase

Define un tipo de objeto del negocio (ej. Ticket, Cliente, Agente). Es el equivalente a una “clase”. Vive por organización y tiene:

• properties — los campos del objeto. Cada una tiene un type:

  Tipo	Para qué	Requiere
  string / number / boolean	escalares simples	—
  date / datetime	fechas ISO 8601	—
  enum	valor de una lista cerrada	enumValues
  reference	apunta a un objeto de otro tipo	referenceType

• links — relaciones tipadas de primera clase hacia otro tipo, con cardinalidad one_to_one / one_to_many / many_to_many (y opcionalmente un inverse).

• version — para optimistic locking (ver abajo).

Object — la instancia

Un MentatObject es una instancia de un OntologyType: un ticket concreto, un cliente concreto. Guarda sus properties y links reales más metadata (createdAt, version, y —si vino de una ingesta— dataSourceId y externalKey).

Los objetos viven en una sola colección plana discriminados por typeId (no una colección por tipo). Su escala objetivo en el MVP es ~50.000 instancias.

Link — la relación

Una relación tipada entre dos objetos (ej. un Ticket solicitadoPor un Cliente). Se declara en el OntologyType y se materializa en cada objeto. La integridad se valida en el backend: no podés crear un link a un objeto inexistente o de otro tipo.

ActionType — el cambio ejecutable

Define una operación que un usuario puede ejecutar sobre los objetos, de forma atómica y auditada. Es el corazón del modelo. Tiene:

• parameters — lo que el operador completa al ejecutar (incluye reference para elegir el objeto target).
• rules — qué cambia en el modelo: modify, create o delete.
• validations — precondiciones: permission (por rol) y stateCheck (una condición sobre una property del target, ej. “el ticket no está cerrado”).
• sideEffects — efectos best-effort post-commit: notification (email) y webhook.
• permissions.roles — qué roles pueden ejecutarla.

ActionExecution — el log inmutable

Cada ejecución de una Action deja un registro inmutable: quién, cuándo, con qué parámetros, qué objetos tocó, qué side effects corrieron, el resultado (success / partial / failed) y la duración. Nunca se modifica. Es el audit log central de Mentat.

DataSource — la fuente externa

Define cómo se puebla la Ontología desde afuera. Tipos: csv_upload, rest_api, webhook y manual. Sus mappings dicen qué campo de la fuente aterriza en qué property de qué tipo, con transformers opcionales (trim, toNumber, parseDate, …).

Un mapping puede marcarse como clave natural (isIdentity): con eso, re-ingestar actualiza los objetos en vez de duplicarlos (upsert por externalKey = "{dataSourceId}:{valor}"). Cada corrida deja un IngestionRun inmutable (análogo al ActionExecution).

AuditEvent — la línea de tiempo

La bitácora unificada del tenant: cada mutación de Ontología, cada ejecución de Action y cada ingesta deja un evento inmutable con su domain (ontology / action / user / datasource), actor, target y diff. Es lo que alimenta el feed de actividad del Dashboard.

Conceptos transversales

Organización (tenant)

Cada cliente es una organización aislada. Todos los datos cuelgan de /organizations/{orgId}/… y las Security Rules garantizan que un usuario solo ve los datos de las organizaciones donde es miembro.

Roles

Se asignan por organización:

Principios que vas a notar en todo

• Validación en el backend, siempre. El frontend dispara; las Cloud Functions validan y escriben. No hay writes directos del cliente.
• Operaciones atómicas. Una Action que toca varios docs es todo-o-nada.
• Optimistic locking (version): si dos personas editan lo mismo, la segunda recibe un conflicto explícito en vez de pisar.
• Soft delete: nada se borra físicamente; se marca deleted.
• Audit inmutable y costos visibles desde el día uno.