Flujo de Comunicaciones

Documento tecnico que describe el sistema completo de comunicaciones de Nvito: la arquitectura de 3 capas, los templates con variables Handlebars, los workflows automatizados con 6 triggers, los 4 canales de envio, las colas Bull con reintentos y el ciclo de vida de mensajes y campanas.

1. Arquitectura de 3 Capas

El sistema de comunicaciones esta dividido en 3 modulos NestJS con responsabilidades claras y sin dependencias circulares:

1.1 Responsabilidades por Capa

1.2 Regla de Arquitectura

La Capa 1 nunca importa a la Capa 2 ni la Capa 3. La Capa 2 nunca importa la Capa 3. Las dependencias fluyen de arriba hacia abajo exclusivamente.

2. Templates de Comunicacion

Los templates usan sintaxis Handlebars para insertar variables dinamicas del invitado y el evento.

2.1 Variables Disponibles

2.2 Estados del Template

2.3 Tipos de Template

3. Workflows Automatizados

Los workflows permiten configurar acciones automaticas que se disparan por eventos del sistema.

3.1 Triggers Disponibles

3.2 Configuracion del Workflow

Cada workflow define:

3.3 Flujo de Ejecucion del Workflow

4. Canales de Envio

4.1 Email (SMTP)

4.2 WhatsApp (Twilio)

4.3 SMS (Twilio)

4.4 Push Notifications

5. Colas Bull (Redis)

5.1 Configuracion de Colas

5.2 Estructura del Job

interface QueueJob {
  id: string;           // UUID del mensaje
  channel: Channel;     // EMAIL | WHATSAPP | SMS | PUSH
  to: string;           // Destinatario (email, phone, pushToken)
  subject?: string;     // Solo email
  body: string;         // Contenido renderizado
  htmlBody?: string;    // Solo email (HTML)
  metadata: {
    eventId: string;
    guestId: string;
    campaignId?: string;
    workflowId?: string;
    templateId: string;
  };
  attempts: number;
  priority: number;     // 1 (alta) a 10 (baja)
}

5.3 Politica de Reintentos

1. Intento 1: Inmediato
2. Intento 2: Despues de backoff * 1 segundos
3. Intento 3: Despues de backoff * 2 segundos
4. Fallo definitivo: Marcar mensaje como FAILED, registrar error

6. Ciclo de Vida del Mensaje

Cada mensaje individual tiene un ciclo de vida rastreable:

7. Campanas Masivas

Las campanas permiten enviar comunicaciones a multiples invitados.

7.1 Estados de la Campana

7.2 Flujo de Campana

7.3 Prevencion de Spam

8. Webhooks de Estado

Los proveedores externos notifican cambios de estado via webhooks:

8.1 Procesamiento de Webhooks

9. Archivos Clave

10. Relacion con Otros Flujos