> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Arquitectura y fronteras

TeLeo es una aplicación web de consola. El cliente no se conecta directamente a
ella: el canal y el workflow transportan los mensajes, mientras que la consola
ofrece a los agentes una vista de tickets y una forma segura de responder.

## Vista lógica

```mermaid
flowchart TD
    customer["Cliente en Super App"] --> chat["Chat / workflow de texto"]
    chat -->|"crear escalado"| ingress["Ingesta server-side de TeLeo"]
    ingress --> twin["HappyRobot Twin"]
    twin --> ticket["Ticket + mensajes + contexto"]
    ticket --> console["Consola TeLeo"]
    console --> agent["Agente humano"]
    agent -->|"respuesta pública"| save["Persistencia del mensaje"]
    save --> webhook["Webhook al workflow"]
    webhook --> customer
    customer -->|"respuesta posterior"| ingress
    console -->|"cierre / de-escalado"| lifecycle["Señal de ciclo"]
    lifecycle --> chat
```

## Capas

| Capa | Responsabilidad | No debe hacer |
|---|---|---|
| Canal y workflow | Detectar que hace falta una persona, mantener la sesión y devolver la respuesta al cliente. | Asumir que un HTTP 200 equivale a una operación de negocio resuelta. |
| Ingesta | Validar autenticación M2M, normalizar contexto, crear de forma idempotente y añadir mensajes. | Exponer credenciales en el payload o crear un ticket por cada mensaje. |
| Aplicación TeLeo | Gestionar ticket, asignación, cola, mensajes, notas privadas, estados y webhooks. | Autenticar al cliente final o sustituir la autoridad de Salesforce/Omega. |
| Twin | Persistir entidades y consultar datos de la aplicación. | Convertirse automáticamente en fuente de verdad de contratos o casos externos. |
| Consola | Mostrar el trabajo permitido a cada agente y enviar acciones al servidor. | Usar el navegador para decidir permisos o enviar una clave M2M. |
| Backends de negocio | Confirmar identidad, contrato, caso, pago o cualquier resultado empresarial. | Delegar esa confirmación en el resumen del bot o en el agente de UI. |

## Almacenamiento

La aplicación no mantiene una base de datos de negocio propia. Las entidades de
TeLeo viven en HappyRobot Twin y se acceden mediante la capa server-side de la
app. El camino SQL con credencial de servicio es el recomendado para el
funcionamiento continuo; existe un camino legacy dependiente de sesión para
compatibilidad. La elección efectiva debe comprobarse en el entorno y la
credencial nunca debe llegar al navegador.

## Fronteras de integración

* **Entrada HappyRobot:** crea el ticket con `session_id`, histórico, resumen y
  metadata mínima.
* **API Super App:** permite que un integrador cree, lea o actualice un ticket
  con autenticación M2M separada.
* **Mensajes del cliente:** vuelven al mismo ticket mediante el identificador de
  sesión estable.
* **Respuesta del agente:** se guarda primero en TeLeo y luego se entrega por
  webhook; las notas privadas no cruzan.
* **Señales:** informan de inicio, de-escalado o cierre de la atención según el
  contrato del workflow.
* **Omega:** el MVP documentado utiliza un enlace saliente a una ficha cuando
  existe un identificador de cuenta autorizado; no presupone iframe ni token de
  agente.

## Escalabilidad y fallos

La ingesta debe tolerar reintentos mediante idempotencia. El webhook puede fallar
después de que la respuesta haya quedado guardada, por lo que el agente no debe
perder su mensaje. La aplicación debe distinguir un error de autenticación, un
fallo de Twin, un fallo del webhook y un destino de negocio no disponible.

Un timeout del canal no permite afirmar que el cliente recibió el mensaje. Un
fallo de señal no debe bloquear la atención, pero sí quedar en logs de
observabilidad sin incluir el secreto ni el transcript completo.

## Entorno y despliegue

TeLeo se despliega como custom app de HappyRobot con Next.js App Router, React y
TypeScript. La app, Twin, webhooks, workflows y backends pueden tener entornos
distintos; todos los payloads deben declarar el entorno de la sesión y nunca
mezclar datos de prueba con producción.

Consulta [la API de integración](/use-cases/super-app/teleo/reference/api) y el
[modelo de datos](/use-cases/super-app/teleo/reference/data-model) para los
contratos que cruzan estas fronteras.