Resumen de arquitectura

Propósito de este documento¶

Este documento describe, en lenguaje accesible, cómo está construida la solución FleteChat v1.0 que Kaeus Inc. desarrollará para Zeverium Group, S.A. No requiere conocimiento técnico previo. Su objetivo es darle al equipo de FleteChat una visión completa del sistema antes de iniciar el desarrollo, y obtener su validación formal sobre las decisiones de diseño que afectan la operación, los costos recurrentes y el manejo de información sensible.

Resumen ejecutivo¶

FleteChat es un sistema construido alrededor de un agente conversacional por WhatsApp que atiende a los clientes finales 24/7, cotiza embarques internacionales, coordina la documentación operativa y mantiene informado al cliente sobre el estado de su carga. Cuando una conversación requiere intervención humana, el sistema escala al equipo operativo de FleteChat, quien atiende desde un panel web interno y devuelve el control al agente al resolver la consulta.

El sistema vive completamente en la nube de Microsoft (Azure), se conecta con WhatsApp Business API de Meta para enviar y recibir mensajes, usa un modelo de inteligencia artificial de Anthropic como cerebro del agente, y guarda toda la información de embarques, clientes y conversaciones en una base de datos central administrada por Kaeus durante el desarrollo y por FleteChat tras el go-live.

El diseño prioriza tres cosas:

1. Que FleteChat opere el sistema sin dependencia técnica externa: las tarifas, los servicios, las plantillas de instructivos y los catálogos los administra el propio equipo de FleteChat desde el panel web.
2. Que la conversación con el cliente final sea rápida y natural: el motor de cotización responde en menos de dos segundos en condiciones normales, y el agente solo pregunta lo que falta.
3. Que la información sensible se maneje conforme a la Ley 81 de Panamá: hay un proceso explícito para que un cliente ejerza sus derechos de acceso, rectificación, eliminación y portabilidad de sus datos.

Vista de alto nivel¶

El siguiente diagrama muestra cómo se relaciona el sistema con sus distintos públicos y servicios externos:

flowchart LR
    cliente[Cliente final<br/>importador / exportador]
    equipo[Equipo FleteChat<br/>operador, gestor de precios, admin]
    sistema[FleteChat<br/>en Azure]
    wa[WhatsApp Business API<br/>Meta]
    ai[Anthropic API<br/>modelo AI]
    email[Proveedor de correo<br/>SMTP]

    cliente <-->|WhatsApp| wa
    wa <--> sistema
    sistema -->|email instructivos| email
    email -->|email| cliente
    equipo -->|panel web HTTPS| sistema
    sistema <--> ai

Cuatro frentes de comunicación:

• Cliente final ↔ FleteChat por WhatsApp: la única vía de cara al cliente para cotizar, aprobar embarques, consultar estatus y recibir instructivos.
• Cliente final ↔ FleteChat por correo electrónico: para verificar el correo durante el alta, recibir el paquete de datos personales tras solicitarlo (Ley 81), y opcionalmente recibir copia de instructivos.
• Equipo FleteChat ↔ FleteChat por panel web: el operador atiende handoffs, el gestor de precios actualiza tarifas, el administrador configura catálogos. Acceso restringido por usuario y rol.
• FleteChat ↔ servicios externos: WhatsApp Business API para enviar/recibir mensajes, Anthropic API para que el agente entienda lenguaje natural, proveedor de correo para envíos transaccionales.

Componentes principales del sistema¶

El sistema está compuesto por cinco componentes lógicos. Todos viven dentro del mismo programa servidor en Azure y comparten una sola base de datos.

Agente conversacional¶

Es el "cerebro" del sistema: lee cada mensaje del cliente final por WhatsApp, decide qué hacer y responde. No es un árbol de decisión rígido ni un menú de opciones: el cliente escribe en lenguaje natural y el agente entiende.

El agente sabe hacer un conjunto acotado de cosas:

• Cotizar un embarque (consulta al motor de cotización).
• Registrar un cliente nuevo (con verificación de teléfono y correo).
• Consultar el estatus de un embarque del cliente.
• Generar reportes y resúmenes de los embarques históricos.
• Detectar cuándo no puede o no debe responder, y escalar a un operador humano.

Para cada acción el agente invoca una "herramienta" interna que ejecuta la operación contra la base de datos. El agente no inventa precios ni datos: cuando responde con información concreta (un precio, un estatus, una fecha), la información proviene del sistema, no del modelo de inteligencia artificial.

Motor de cotización¶

Calcula el precio total de un embarque sumando los cargos de todos los servicios aplicables. Lee la lista de precios vigente para el nivel corporativo del cliente, busca la tarifa que aplica a la combinación solicitada (modalidad de transporte, tipo de operación, Incoterm, ruta) y produce un desglose línea por línea.

Tres propiedades importantes del motor:

• Es completamente parametrizable: las tarifas, los servicios, los Incoterms, las modalidades y los aeropuertos/puertos operados los configura FleteChat. Kaeus no toca el código para que FleteChat suba un precio nuevo o desactive una ruta.
• Soporta wildcards en orígenes y destinos: una sola regla puede cubrir "cualquier puerto chino" o "cualquier puerto de Panamá", lo que reduce la cantidad de filas a mantener.
• Es determinístico: la misma cotización con los mismos parámetros y la misma lista de precios produce siempre el mismo resultado. Esto es importante porque las cotizaciones tienen vigencia y deben poder reproducirse para auditoría.

Cuando una combinación solicitada no tiene tarifa configurada (porque la ruta no se opera, o porque requiere intervención humana), el motor devuelve "combinación no soportada" y el agente escala automáticamente a un operador.

Gestión de embarques e instructivos¶

Cuando un cliente aprueba una cotización por WhatsApp, este componente toma el control:

1. Genera el número de embarque y el número de tracking.
2. Le envía al cliente un enlace privado a un formulario web donde completa los datos operativos (suplidor, receptor, instrucciones de carga). El enlace tiene un período de validez configurable y no requiere que el cliente cree una contraseña.
3. Al recibir el formulario completo, genera tres documentos PDF de instructivo: uno para el suplidor del cliente, uno para el operador logístico de FleteChat y uno interno.
4. Distribuye los instructivos automáticamente por WhatsApp y correo electrónico.
5. Construye la lista de estatus del embarque (la secuencia de hitos que el equipo operativo irá marcando) según los servicios contratados.

A partir de allí, el embarque queda visible en el panel web y el operador actualiza su estatus a medida que avanza la operación. Cada actualización dispara una notificación automática al cliente por WhatsApp.

Panel web (backoffice)¶

Aplicación web de uso interno de FleteChat. Tres roles diferenciados, con acceso restringido:

• Administrador: configura los catálogos del sistema (servicios logísticos, modalidades, Incoterms, niveles corporativos, plantillas de mensajes proactivos), gestiona usuarios y parámetros globales.
• Gestor de precios: administra las listas de precios. Sube actualizaciones desde una plantilla Excel; el sistema valida y reporta conflictos antes de aplicar los cambios.
• Operador: actualiza estatus de tracking, atiende conversaciones que el agente escala (handoff), consulta los reportes operativos.

El panel se conecta con la misma base de datos que el agente de WhatsApp, así que las operaciones del operador en el panel se reflejan inmediatamente en lo que el agente sabe.

Notificaciones y procesos automáticos¶

El sistema tiene un componente que ejecuta tareas en segundo plano sin intervención humana:

• Envía recordatorios por WhatsApp cuando un cliente aprobó una cotización pero no completa el formulario operativo.
• Distribuye los instructivos al cerrarse el formulario.
• Notifica al cliente cuando el operador marca un nuevo estatus en su embarque.
• Avisa al equipo de FleteChat cuando un contrato corporativo se aproxima a su vencimiento.

Estos procesos corren con tolerancia a fallos: si un envío de WhatsApp falla por una caída temporal de Meta, el sistema reintenta con un retraso creciente antes de marcar el evento como no entregado.

Tecnologías utilizadas¶

El sistema se construye con tecnologías maduras, ampliamente adoptadas en la industria, con comunidad activa y soporte a largo plazo. Esta sección las nombra para referencia; no requiere conocimiento técnico para entenderla.

El sistema se entrega como un único proceso de aplicación: el mismo servidor atiende la API, sirve el panel web React, ejecuta el agente y los procesos de fondo. Esto simplifica el despliegue y la operación: un solo recurso a monitorear, un solo lugar donde aplicar configuración, un solo origen de logs.

Servicios externos que el sistema utiliza¶

FleteChat se apoya en cuatro servicios de terceros. Los costos de estos servicios los paga directamente FleteChat al proveedor, no a Kaeus.

WhatsApp Business API (Meta)¶

Es la única vía de comunicación con el cliente final. Permite recibir mensajes entrantes (cuando el cliente escribe) y enviar mensajes salientes (respuestas del agente, notificaciones proactivas). Las notificaciones proactivas de Meta requieren plantillas pre-aprobadas; FleteChat gestiona ese proceso de aprobación con apoyo de Kaeus durante la Fase 1.

El sistema soporta múltiples números de WhatsApp simultáneamente, lo que permite a FleteChat operar varias líneas comerciales sin cambiar el sistema.

Modelo de IA (Anthropic API)¶

Es el motor que le permite al agente entender el lenguaje natural del cliente. Por cada mensaje recibido y cada respuesta generada, el sistema consume un servicio de Anthropic que se factura por uso. La elección del modelo y la configuración del agente se afina durante la Fase 3 con escenarios reales del negocio de FleteChat.

Naturaleza probabilística: dado que el modelo es un sistema de inteligencia artificial, no se garantizan respuestas completamente libres de errores. El sistema mitiga esto con tres mecanismos: (a) las acciones concretas del agente (cotizar, registrar, etc.) las ejecutan herramientas internas y no el modelo, (b) hay un mecanismo de escalación a operador humano cuando el agente detecta que no puede resolver, (c) la Fase 3 incluye sesiones de calibración del agente con escenarios reales.

Correo electrónico¶

El sistema envía correos transaccionales en cuatro situaciones: enlace de verificación durante el alta de cliente, distribución de instructivos a proveedor y operador logístico, paquete de datos personales tras solicitud bajo Ley 81, y alertas internas al equipo de FleteChat (ej. vencimiento de contrato corporativo).

Todos los correos enviados quedan registrados con su estado (enviado, entregado, fallido) para auditoría.

Infraestructura en la nube de Microsoft (Azure)¶

El sistema corre en una suscripción Azure provista por FleteChat. La sección siguiente detalla los recursos aprovisionados y la estimación de costo mensual.

Despliegue en Azure y estimación de costo mensual¶

Recursos aprovisionados¶

flowchart TB
    subgraph azure[Suscripción Azure de FleteChat]
        app[Container App<br/>servidor de aplicación]
        acr[Container Registry<br/>imágenes Docker]
        db[(PostgreSQL Flexible Server<br/>base de datos)]
        blob[(Blob Storage<br/>PDFs y archivos)]
        kv[Key Vault<br/>secretos y credenciales]
        logs[Log Analytics + Application Insights<br/>logs y monitoreo]
    end

    acr -->|pull de imagen| app
    app --> db
    app --> blob
    app --> kv
    app --> logs

Kaeus aprovisiona estos recursos durante la Fase 1 mediante scripts reproducibles. La configuración queda documentada y FleteChat puede recrearla en otra suscripción si lo requiere.

El servidor de aplicación se despliega como imagen Docker sobre Azure Container Apps. Esto desacopla la versión de Python del runtime gestionado de Azure y permite usar Python 3.14 desde el día uno. Container Apps es el servicio serverless de Azure para contenedores: escala automáticamente según demanda y se factura por uso.

Estimación de costo mensual¶

Las cifras a continuación son una estimación inicial basada en tarifas de Azure de la región East US 2 (similares a la región más cercana a Panamá, Brazil South) y un volumen estimado de arranque (alrededor de 50 a 200 cotizaciones diarias). Los valores reales pueden variar según volumen real, región seleccionada, y descuentos por reserva anual.

Costos de Azure (recursos de infraestructura)¶

Nota sobre la elección de SKU de PostgreSQL. El tier Burstable (B-series) acumula créditos de CPU y los gasta cuando hay carga; al agotarse los créditos, el rendimiento cae bruscamente, lo que es inaceptable para una aplicación conversacional 24/7. D2ads_v5 es el menor SKU production-ready del tier General Purpose (CPU dedicado, desempeño predecible). La variante AMD es ~10% más económica que su equivalente Intel (D2ds_v5) con la misma capacidad.

Costos de servicios externos por uso¶

Estos servicios los paga FleteChat directamente al proveedor; no van por la factura de Azure. Las cifras dependen del volumen real de uso:

Nota sobre WhatsApp Business API. Desde julio 2025, Meta cambió el modelo de cobro: - Mensajes "service" (respuestas de la empresa enviadas dentro de las 24 horas posteriores al último mensaje del cliente) son gratis sin límite. - Mensajes "template" utility (notificaciones proactivas como cambios de estatus enviados fuera de la ventana de 24h) cuestan aproximadamente 0.007 USD/mensaje para destinos en Panamá y Centroamérica. - Mensajes "template" marketing son más caros (~0.03 USD/mensaje) pero no se prevén en v1.0.

Para FleteChat, la mayoría del tráfico es conversacional (cliente inicia la conversación al cotizar): cotizar, consultar tracking, registrarse, completar formulario. Todo eso cae en service messages gratis. Solo se cobran las notificaciones automáticas de cambio de estatus que llegan días después del último mensaje del cliente. A volumen de arranque (~50 embarques activos/mes con ~4 cambios de estatus cada uno fuera de ventana), el costo ronda 5 – 30 USD/mes.

Total mensual estimado¶

Cómo escala el costo¶

• Más cotizaciones por día aumenta el costo del modelo de IA y, marginalmente, el del App Service. Cada cotización promedio consume aproximadamente medio centavo en Anthropic API.
• Más conversaciones proactivas (notificaciones, recordatorios) aumenta el costo de WhatsApp. Las plantillas tipo "utility" (cambio de estatus, instructivos) cuestan menos que las de marketing.
• Más volumen de embarques con instructivos aumenta el almacenamiento Blob; el incremento es marginal (centavos por GB/mes).
• Crecimiento sostenido puede requerir aumentar la capacidad del Container App (a 1 vCPU + 2 GB, ~75 USD/mes) o subir el SKU de PostgreSQL (de D2ads_v5 a D4ads_v5). Cada salto duplica aproximadamente el costo del recurso afectado.

Optimizaciones disponibles a futuro¶

• Reservas anuales en Azure: descuentos del 30 al 40 % en App Service y PostgreSQL al comprometerse a un año.
• Caché de respuestas conversacionales: reduce llamadas al modelo de IA en consultas repetitivas.
• Tier "frío" en Blob Storage: para archivos de más de 6 meses sin acceso, baja el costo de almacenamiento aproximadamente 50 %.

Estas optimizaciones no entran en el alcance de la versión 1.0 y se evalúan tras estabilizar la operación.

Datos e información¶

Qué información guarda el sistema¶

• Clientes y sus contactos: nombre, identificación tributaria, dirección fiscal, números de teléfono verificados, correos verificados, persona de contacto.
• Conversaciones de WhatsApp: cada mensaje entrante y saliente, con su contenido, momento de envío y estado de entrega/lectura.
• Cotizaciones: cada cotización emitida con su desglose línea por línea, vigencia, y una fotografía del catálogo y la lista de precios al momento de cotizar (para garantizar reproducibilidad histórica).
• Embarques: número de tracking, datos operativos del formulario, secuencia de estatus, instructivos generados.
• Catálogos del negocio: servicios logísticos, tarifas, niveles corporativos, plantillas de instructivos, parámetros globales.
• Bitácora de auditoría: cada acción relevante (alta de cliente, emisión de cotización, aprobación de embarque, cambio de estatus, modificación de tarifas) queda registrada con quién la hizo y cuándo.

Una sola fuente de verdad¶

Toda la información del sistema vive en una única base de datos central. No hay copias paralelas ni sincronizaciones entre sistemas. Esto evita inconsistencias: lo que el operador ve en el panel web es exactamente lo que el agente de WhatsApp sabe.

La base de datos se respalda automáticamente con la frecuencia que define el plan de Azure. La política específica de respaldo se acuerda en Fase 1.

Datos personales y Ley 81 de Panamá¶

El sistema implementa los derechos del titular establecidos por la Ley 81:

• Acceso: el cliente puede solicitar por WhatsApp un paquete con todos sus datos. El sistema lo genera y envía al correo verificado del cliente.
• Rectificación: el cliente solicita corrección de datos; el operador la ejecuta desde el panel web tras verificar identidad.
• Eliminación: el cliente puede solicitar la eliminación de sus datos. El sistema anonimiza la información personal (no la borra físicamente) para preservar la integridad histórica de los embarques. El historial operativo se conserva pero los campos personales se reescriben con un placeholder. Esta operación queda registrada en la bitácora como evidencia del ejercicio del derecho.
• Portabilidad: el paquete de datos se entrega en formato legible.
• Oposición: el cliente puede solicitar dejar de recibir mensajes proactivos no esenciales (alertas, recordatorios opcionales) sin perder la capacidad de cotizar y operar.

Existe un rol específico (DPO — Delegado de Protección de Datos) en el panel web con acceso a las solicitudes Ley 81 y la auditoría de las acciones realizadas en respuesta.

Retención de información¶

El sistema retiene los datos operativos (cotizaciones, embarques, instructivos, conversaciones) por un período mínimo configurable (por defecto siete años, ajustable según política interna de FleteChat). La purga automática por antigüedad no entra en el alcance de la versión 1.0; en esta versión, los datos solo se anonimizan o eliminan por solicitud explícita del titular. La auto-purga por retención se prevé como mejora posterior, antes de que cumpla el período el dato más antiguo en producción.

Seguridad¶

Acceso al panel web¶

Cada miembro del equipo de FleteChat tiene un usuario propio con un rol asignado (administrador, gestor de precios, operador, DPO). Las contraseñas se almacenan de forma irrecuperable (cifrado moderno). El acceso al panel está restringido por dirección de origen cuando FleteChat así lo defina; por defecto es público pero requiere autenticación.

Las acciones críticas (modificación de catálogos, aprobación de cambios de tarifas, ejecución de derechos Ley 81) requieren autenticación reciente y quedan registradas en la bitácora con el usuario que las realizó.

Protección de la comunicación¶

Toda la comunicación con el sistema viaja cifrada (HTTPS/TLS). Los webhooks de WhatsApp se validan con la firma criptográfica que Meta provee, lo que evita que un tercero envíe mensajes falsos al sistema haciéndose pasar por Meta.

Los enlaces enviados al cliente final (formulario operativo, paquete de datos personales) usan tokens temporales con vencimiento. Un token expirado deja de funcionar incluso si el enlace cae en manos equivocadas.

Identificación del cliente final por WhatsApp¶

El sistema identifica al cliente automáticamente por el número de teléfono que envía el mensaje, sin pedir credenciales. Este enfoque acepta el riesgo de que el dispositivo del cliente sea utilizado por un tercero (cualquiera que tenga el teléfono puede escribir como el cliente). Es una decisión consciente: WhatsApp no soporta autenticación de doble factor por sesión, y exigir credenciales rompería la experiencia conversacional. Las acciones críticas (aprobación formal de cotizaciones, ejecución de derechos Ley 81) requieren confirmación adicional por correo o canal alterno cuando aplique.

Disponibilidad y soporte¶

Cómo se sabe que el sistema está funcionando¶

El sistema emite logs centralizados que registran cada solicitud, cada error y cada operación crítica. Hay tableros de monitoreo donde el equipo técnico puede ver en tiempo real el ritmo de mensajes procesados, la latencia del motor de cotización y la tasa de errores.

Cuando ocurre un error que afecta al cliente final (caída temporal de WhatsApp, fallo del modelo de IA, error interno), el sistema responde al cliente con un mensaje claro y, si corresponde, escala a un operador humano automáticamente.

Tolerancia a fallos puntuales¶

El sistema está diseñado para tolerar fallos transitorios:

• Si un mensaje saliente falla por caída de Meta, se reintenta con espaciado creciente.
• Si el servicio de IA tiene latencia alta, el sistema espera hasta el límite acordado y luego informa al cliente que no pudo procesar la consulta.
• Si la base de datos se cae, el sistema deja de aceptar mensajes nuevos hasta que recupera conectividad. No se pierden mensajes ya recibidos, porque WhatsApp los reintenta.

Soporte post go-live¶

El alcance de soporte post-implementación se define en el contrato. Kaeus entrega documentación operativa, capacita al equipo en el uso del panel web, y realiza un período de acompañamiento durante la estabilización inicial.

Lo que la arquitectura previene por diseño¶

Estos son los invariantes que el sistema garantiza estructuralmente, no por convención. Son útiles como puntos de validación con FleteChat:

• Un mismo número de teléfono no puede pertenecer a dos clientes activos simultáneamente.
• Un mismo correo no puede ser el correo principal de dos clientes activos simultáneamente.
• Un cliente tiene un solo nivel corporativo activo a la vez (con período de vigencia explícito).
• Una cotización aprobada produce un solo embarque (no se pueden duplicar embarques por doble click).
• Una cotización emitida es inmutable: una vez calculada, su contenido no se puede modificar — si hay que cambiarla, se emite una nueva.
• El número de tracking es único globalmente y nunca se reutiliza.
• Una operación no completada no deja datos parciales: el sistema usa transacciones, así que o se ejecuta toda la operación o no se ejecuta ninguna.
• Cada acción crítica queda en bitácora: no hay forma de modificar un dato sin dejar rastro.

Lo que requerimos de FleteChat para operar¶

El sistema depende de cosas que solo FleteChat puede proveer. Para que el cronograma se cumpla, las siguientes son responsabilidad del cliente:

• Cuenta de WhatsApp Business API aprobada por Meta antes del inicio de UAT (Fase 3). El proceso de aprobación de Meta puede tomar semanas y debe iniciarse temprano.
• Llaves de acceso al modelo de IA de Anthropic (cuenta y crédito).
• Suscripción Azure con permisos para crear los recursos definidos en el diseño técnico.
• Plantillas de mensajes proactivos aprobadas por Meta antes del inicio de UAT (Kaeus apoya el diseño durante Fase 1, pero la cuenta es del cliente).
• Datos de levantamiento (formatos L1–L4) completados antes del inicio del desarrollo. Esto incluye servicios logísticos, lista de precios inicial, niveles corporativos, aeropuertos y puertos operados.
• Punto de contacto único con capacidad de tomar decisiones, disponible durante todo el proyecto.
• Disponibilidad de usuarios funcionales para las pruebas de aceptación (UAT).

Validación esperada del cliente¶

Solicitamos a FleteChat confirmar formalmente los siguientes puntos antes de cerrar la Fase 1 de Diseño:

1. Modelo conversacional: el cliente final interactúa exclusivamente por WhatsApp; las verificaciones de correo y los formularios usan enlaces temporales sin contraseña.
2. Motor de cotización parametrizable: las tarifas y servicios los administra el equipo de FleteChat sin dependencia de Kaeus.
3. Identificación por número de teléfono: aceptamos el riesgo descrito en la sección de seguridad.
4. Ley 81: el modelo de anonimización (no eliminación física) preserva integridad histórica y queda registrado en bitácora.
5. Una base de datos central: no hay sincronización con sistemas externos del cliente en v1.0.
6. Soporte de servicios externos: WhatsApp, Anthropic y Azure los provee y paga FleteChat directamente.
7. Sin actualizaciones automáticas de tracking desde transportistas: los estatus los actualiza manualmente el operador.
8. Retención por defecto de siete años para datos operativos, ajustable por configuración.

La validación de este documento por parte de FleteChat habilita el inicio de la Fase 2 (Desarrollo del MVP).

Glosario mínimo¶

• Agente conversacional: el componente que conversa con el cliente final por WhatsApp.
• Backoffice: panel web interno usado por el equipo de FleteChat.
• Embarque: una operación logística aprobada con número de tracking asignado.
• Cotización: cálculo del precio total de un embarque. Es inmutable una vez emitida.
• Handoff: el momento en que el agente escala una conversación a un operador humano.
• Incoterm: estándar internacional que define qué responsabilidades asumen vendedor y comprador (EXW, FOB, CIF, etc.).
• Instructivo: documento PDF generado para cada embarque que coordina las acciones del proveedor, el operador logístico y el equipo interno.
• Modalidad: forma de transporte (aéreo, marítimo consolidado LCL, marítimo contenedor completo FCL).
• Nivel corporativo: clasificación del cliente que determina qué lista de precios se le aplica (estándar, silver, gold, premium).
• Tracking: el número y la secuencia de estatus que permite al cliente seguir su embarque.
• UAT: pruebas de aceptación con el cliente, antes del go-live.
• Ley 81: Ley de Protección de Datos Personales de Panamá.