Documentation Index
Fetch the complete documentation index at: https://mintlify.com/KevinhosUTP/Automatizacion-Lurwis/llms.txt
Use this file to discover all available pages before exploring further.
Visión General
Automatización Lurwis está construida con una arquitectura de microservicios asíncronos orquestados por n8n. El sistema separa la recepción de mensajes (Receptor) del procesamiento inteligente (Procesador) para maximizar la confiabilidad y escalabilidad.Diagrama de Arquitectura Completo
Componentes Principales
1. Workflow Receptor
Propósito: Punto de entrada ultrarrápido que recibe webhooks de Meta y los almacena temporalmente.Características Clave
- Responde en < 100ms para evitar timeouts de Meta
- Filtra eventos innecesarios (status updates, read receipts)
- Agrupa mensajes rápidos del mismo usuario en un solo contexto
- No contiene lógica de negocio (solo enrutamiento)
Flujo Interno del Receptor
Webhook Trigger
El nodo Webhook escucha en
POST /meta-verify con dos tipos de peticiones:GET (Verificación): Meta valida el webhook enviando hub.mode, hub.verify_token y hub.challenge. El sistema verifica el token y devuelve el challenge.POST (Mensaje): Meta envía el payload completo del mensaje con estructura:Filtrado de Mensajes Vacíos
Nodo IF llamado “Identificador de vacíos” valida:Esto descarta confirmaciones de entrega y estados leídos que Meta envía continuamente.
Extracción de Datos
Nodo Set llamado “Extractormensajes” limpia el payload complejo y extrae solo:
from: Número de teléfono (ej:51900769907)text.body: Contenido del mensajeid cliente: ID único del mensaje de WhatsAppid mensajero: Phone Number ID de Meta (para responder)profile_name: Nombre del contacto en WhatsApp
Sistema de Buffer en Redis
Secuencia de 4 nodos Redis para agregar mensajes:
- Buffer: Buscar - Busca si existe
buffer_{telefono}en Redis - Buffer: Agregar Mensaje - Código JS que concatena:
- Buffer: Guardar - Guarda el texto agregado con TTL 30s
- Buffer: Timestamp - Actualiza
ts_{telefono}con timestamp actual - Buffer: Meta - Guarda
meta_{telefono}con el ID del mensajero (TTL 120s)
Si el cliente envía “Hola”, “Quiero”, “Un ceviche” en 5 segundos, Redis agrupa todo como “Hola\nQuiero\nUn ceviche” para que el Procesador lo vea como un solo contexto.
2. Workflow Procesador
Propósito: Motor de inteligencia que consume el buffer, clasifica intenciones y ejecuta lógica de negocio con agentes especializados.Características Clave
- Se ejecuta cada 10 segundos automáticamente (Schedule Trigger)
- Procesa múltiples usuarios en paralelo
- Usa Google Gemini para clasificación e interacción
- Mantiene memoria conversacional en MongoDB
- Escribe pedidos confirmados en PostgreSQL
Flujo Interno del Procesador
Schedule Trigger
Cada 10 segundos, el workflow se ejecuta automáticamente. Esto es polling asíncrono - desacopla la recepción (Receptor) del procesamiento.
Buscar Usuarios Activos
Nodo “Redis: Buscar usuarios activos” ejecuta:Esto devuelve todas las keys de timestamp, ej:
Expandir a Items Individuales
Nodo “Code: Expandir usuarios” convierte el objeto en array de items:n8n procesa cada item en paralelo, permitiendo atender múltiples clientes simultáneamente.
Validar Timeout del Buffer
Nodo “If” verifica si pasaron más de 8 segundos desde el último mensaje:Si es
true, el cliente dejó de escribir → procesar ahora. Si es false, esperar 10 segundos más (siguiente ciclo).Leer y Eliminar Buffer
Secuencia de nodos que:
- Lee
buffer_{userId}(mensajes concatenados) - Lee
meta_{userId}(ID del mensajero) - Elimina ambas keys de Redis
- Elimina
ts_{userId}
Recrear Estructura Extractormensajes
Nodo “Extractormensajes” (sí, mismo nombre que en Receptor) formatea:
Validar Pedido Existente
Nodo PostgreSQL “Validar si tiene pedido o no” ejecuta:Si devuelve un registro, el cliente tiene un pedido pendiente.
Bifurcación: ¿Tiene Pedido?
Nodo IF “¿Tiene Pedido Pendiente?” decide:SI tiene pedido pendiente → Activar “Detector de pedidos” (agente que pregunta si quiere modificar o solo consultar)NO tiene pedido → Ir directo al “Agente Clasificador”
Clasificación de Intención
Agente Clasificador (Google Gemini Flash) analiza el mensaje con este prompt:Usa memoria en MongoDB colección
historial_clasificador para recordar conversaciones previas.3. Agentes Especializados
Agente Pedidos (Más Complejo)
Wilson - Pedidos
Especialista en gestión de órdenes, navegación del menú y confirmación de compras.
- Usa Google Gemini Pro (modelo pensante) para lógica compleja
- Tiene 3 herramientas SQL conectadas a PostgreSQL:
consultar_categorias: Lista categorías activas (Ceviches, Chicharrones, etc.)consultar_platos: Lista platos de una categoría con precios por tamañoverificar_plato: Calcula subtotal dado ID del plato, tamaño y cantidad
- Memoria en MongoDB colección
historial_pedidos(contexto de 25 mensajes) - Valida que el cliente diga explícitamente “confirmo” antes de guardar
totalfinal > 0 (indica que el cliente dijo “confirmo”).
Si es true, otro IF “¿Es pedido nuevo o existente?” decide:
Modificar Pedido Existente:
Si la query falla (por error de sintaxis o conexión), el flujo va al output de error del nodo y envía un mensaje de disculpa al cliente con código de referencia.
Agente General
Wilson - Info
Responde preguntas frecuentes sobre ubicación, horarios, métodos de pago y redes sociales.
- Usa Gemini Flash (modelo rápido) para respuestas sencillas
- NO tiene herramientas SQL (información estática)
- Memoria en MongoDB colección
historial_general(10 mensajes)
Agentes de Reservas (En Desarrollo)
4. Bases de Datos
PostgreSQL: Datos Estructurados
Schema de Menú (Normalizado):El campo
detalle_pedido es JSONB para flexibilidad. Permite agregar atributos personalizados sin alterar el schema.MongoDB: Memoria Conversacional
LangChain usa MongoDB para persistir el historial de chat de cada agente: Estructura de Documento:historial_clasificador: Conversaciones del clasificadorhistorial_pedidos: Conversaciones del agente de pedidos (contexto: 25 msgs)historial_reservas: Conversaciones del agente de reservas de mesas (15 msgs)historial_eventos: Conversaciones del agente de eventos (15 msgs)historial_general: Conversaciones del agente general (10 msgs)
El parámetro
contextWindowLength limita cuántos mensajes históricos se envían al LLM en cada request, equilibrando costo y contexto.Redis: Buffer Temporal
Keys Almacenadas:-
buffer_{telefono}: Mensajes concatenados con\n- TTL: 30 segundos
- Ejemplo:
"Hola\nQuiero un ceviche\nPersonal"
-
ts_{telefono}: Timestamp del último mensaje- TTL: 30 segundos
- Ejemplo:
"1771550707733"
-
meta_{telefono}: ID del mensajero de WhatsApp- TTL: 120 segundos (más largo para no perder referencia)
- Ejemplo:
"947279508470714"
5. Integración WhatsApp (Meta Business API)
Webhooks de Meta: Meta envía webhooks para varios eventos, pero el sistema solo procesamessages:
Patrones de Diseño Implementados
1. Asynchronous Processing (Polling)
En lugar de que el Receptor ejecute la IA sincrónicamente (causando timeouts), usa un patrón de cola:- Meta nunca recibe timeouts
- Múltiples mensajes del mismo usuario se agrupan
- Fallos en la IA no afectan la recepción de webhooks
2. Agent Specialization
Cada agente tiene un prompt optimizado para su dominio:- Prompts más cortos y precisos
- Menor alucinación por contexto limitado
- Fácil agregar nuevos agentes (ej: Quejas, Promociones)
3. Memory Segmentation
Cada agente tiene su propia colección en MongoDB:- No contamina contextos (pedidos no ven conversaciones de info general)
- Ahorro de tokens en requests a Gemini
- Facilita análisis de métricas por tipo de interacción
4. Idempotent Operations
El sistema maneja duplicados:totalfinal > 0.
Consideraciones de Seguridad
Verify Token
El webhook valida
hub.verify_token para evitar webhooks falsos de terceros.SSL/TLS
Meta requiere que el webhook use HTTPS. Configura certificados válidos en tu servidor n8n.
Rate Limiting
Implementa límites de mensajes por usuario en Redis (ej: máx 10 msgs/minuto) para evitar spam.
SQL Injection
Las herramientas SQL de n8n usan parámetros seguros. Nunca concatenes strings en queries.
Escalabilidad y Rendimiento
Cuellos de Botella Actuales
- Schedule Trigger de 10s: Si hay 100 usuarios en buffer, se procesan en lote. Considera reducir a 5s en producción.
- Gemini Rate Limits: Google AI Studio tiene límites gratuitos. Usa Vertex AI para producción sin límites.
- Redis Single Instance: Para alta disponibilidad, usa Redis Cluster o Upstash con replicación.
Optimizaciones Recomendadas
Cachear Menú en Redis
Las categorías y platos cambian poco. Cachéalos en Redis con TTL de 1 hora para reducir queries a PostgreSQL.
Paralelizar Agentes
Si un cliente pide información general Y hace un pedido, ejecuta ambos agentes en paralelo y fusiona respuestas.
Usar Gemini Batch API
Agrupa múltiples clasificaciones en un solo request batch para ahorrar latencia.
Monitoreo y Métricas
Logs en n8n
Cada ejecución guarda:- Input del webhook o Schedule Trigger
- Output de cada nodo
- Errores con stack trace
Error Workflow
El sistema incluye un Error Workflow conectado al Receptor que envía notificaciones al WhatsApp personal del administrador cuando ocurre una falla crítica.
- En el workflow Receptor, ve a Settings → Error Workflow
- Selecciona tu workflow de notificaciones
- El error workflow recibe el objeto de error y puede enviar mensajes con detalles
Próximos Pasos
Workflow Receptor
Explora cada nodo del Receptor en detalle
Workflow Procesador
Profundiza en los agentes y herramientas SQL