Arquitectura

El mapa

 Navegador          App nativa (en desarrollo)
     │                      │
     ▼                      ▼
 ┌─────────────── Web (Next.js) ──────────────┐
 │ Páginas: Server Components                 │
 │ BFF: reenvía al backend con la sesión      │
 └─────────────────────┬──────────────────────┘
                       │  el navegador nunca habla
                       ▼  directo con el backend
 ┌──────────── BoostAPI (NestJS) ─────────────┐
 │ Reglas · permisos por petición · datos     │
 │ Canales · workflows · tiempo real          │
 └──┬───────┬────────┬─────────┬──────────┬───┘
    │       │        │         │          │
  MySQL   Zauru    Meta      Amazon     Amazon S3,
  (CRM)   (ERP)  (WhatsApp,   SES       SQS y
                 Messenger, (correo)    EventBridge
                 Instagram)             (archivos
                                        y colas)

El backend habla directo con Meta y con Amazon SES: no hay otro servicio de mensajería en medio. Además recibe avisos de Zauru (órdenes y facturas nuevas) y del procesador de pagos de los links de pago, y consulta INFILE para llenar el nombre a partir de un NIT o un CUI.

Las piezas

La web (`apps/web`)

Next.js con App Router. Las pantallas del CRM viven bajo un grupo de rutas protegido; las páginas públicas (la cotización, el pedido desde el chat, las legales, el ingreso) viven fuera de él.
Server Components primero. La página pide sus datos en el servidor y le pasa props a componentes de cliente solo donde hace falta interacción.
BFF. Todo lo que el navegador necesita del backend pasa por manejadores de la propia web, que agregan la sesión de la persona y reenvían. Así las credenciales nunca llegan al navegador y el backend sigue siendo el único que decide permisos.
Sesión dual. Al entrar, la web valida la identidad con Zauru y el acceso con BoostAPI, y guarda el resultado en una sesión cifrada del servidor. La sesión de Zauru la administra el backend.
Tiempo real. La web se suscribe por sockets a los eventos del backend (mensajes nuevos, cambios de estado, notificaciones) y, si el socket cae, consulta cada tanto como respaldo.
Diseño. Tema oscuro, un solo acento de color y tokens definidos en la hoja de estilos global; el canon visual está en apps/web/docs/DESIGN.md. La librería de componentes de la nueva versión, copiada de Figma, se ve en una pantalla interna (Assets) que solo abre el equipo de plataforma.

Los paquetes compartidos (`packages/*`)

Paquete	Para qué
`@repo/shared-types`	Los tipos de datos que comparten web y móvil.
`@repo/api-client`	Cliente HTTP independiente de la plataforma.
`@repo/crm-services`	La capa de servicios del CRM, con una implementación real y otra de ejemplo.
`@repo/icons`	Los íconos, para web y móvil.
`@repo/ui`	Primitivos de interfaz compartidos (en desarrollo).
`@repo/typescript-config`	Configuraciones de TypeScript.
`@repo/dev-mobile-bff`	Túnel para desarrollar la app móvil contra la web local.

La app móvil (`apps/native`)

Expo y React Native. Replica las pantallas de la web con la misma identidad visual y usa la web como BFF: el ingreso con Zauru vuelve a la app por un enlace profundo y la app intercambia el código a través de la web. Está en desarrollo; la experiencia móvil de hoy es la web en el teléfono.

El backend (BoostAPI)

NestJS sobre MySQL 8, desplegado en Render. Es la autoridad: resuelve en cada petición quién es la persona, en qué entidad está, qué permisos tiene y sobre qué registros. Además:

Zauru: identidad, clientes, productos, precios, existencias, facturas, pagos y órdenes. Boost lee de Zauru al momento y escribe en él (clientes, órdenes, cobros) con los usuarios de servicio de cada entidad.
Meta: WhatsApp (API oficial), Messenger e Instagram, y los comentarios de Facebook e Instagram. Lo que entra (mensajes, estados, reacciones, clics de anuncios) llega por webhook a un receptor que verifica la firma y deja el aviso guardado en una cola antes de responderle a Meta. Después, un proceso lo normaliza, lo guarda como hilo y mensaje del canal y lo proyecta al CRM (contacto, lead, conversación) y al motor de workflows. Lo que sale pasa por un único servicio de envío, que guarda cada envío antes de hacerlo para no mandarlo dos veces y comprueba la ventana de 24 horas del hilo.
Credenciales de los canales: los accesos de Meta y del correo se guardan cifrados, fuera del alcance de las personas y de las herramientas; solo los procesos del backend que los necesitan los usan, y cada uso queda auditado.
Amazon SES: el correo de los buzones de cada entidad, de entrada y de salida.
Amazon S3: archivos y multimedia (adjuntos, imágenes, documentos). La base guarda solo la referencia al archivo; para verlo, la web pide al backend una dirección firmada de pocos minutos, y el backend primero comprueba que la persona ve ese chat.
Amazon SQS y EventBridge: las colas del ingreso de Meta y del correo, y las colas y los temporizadores del motor de workflows y de los canales (esperas, vencimientos, reintentos). Cada entorno tiene las suyas: un proceso en la computadora de alguien nunca consume las de producción.

Los workflows

El motor corre dentro del backend. Cada entidad tiene un usuario de servicio con el que corren sus workflows, y sin él no se pueden encender. Cada número o página tiene además su interruptor de workflows: apagado, los mensajes de ese canal llegan al chat pero no disparan ni reanudan workflows. Un canal nuevo nace con los workflows encendidos si la entidad tiene su usuario de servicio y no los tiene apagados, y el equipo de plataforma los enciende o apaga para toda la entidad desde Configuraciones → Workflows.

Las documentaciones (`apps/docs`, `apps/manual`)

Dos sitios estáticos con Astro: esta documentación y el manual de usuario. Están separados a propósito: el manual lo escribe y lee gente que usa Boost, sin detalles técnicos.

Invariantes que conviene tener presentes

El backend decide los permisos; la web solo los refleja. Una pantalla que esconde un botón no está protegiendo nada.
El navegador nunca llama al backend directo. Todo pasa por el BFF de la web.
Todo pertenece a una entidad. Una persona trabaja en una entidad a la vez, y los datos, ajustes y canales son por entidad.
Zauru manda en lo que es suyo. Boost no guarda copias de existencias ni de saldos: los consulta.
Enviar a Meta o por correo pasa siempre por el único servicio de envío del backend. Ninguna otra pieza llama a Meta o a SES para mandar un mensaje.
Un día del usuario es un día de Guatemala. La base guarda instantes en UTC; quien muestra o filtra por día convierte.
Una vista previa nunca apunta a producción. Los entornos de prueba usan sus propias credenciales, colas y servicios.
Ningún script levanta el backend completo contra producción, porque encendería sus procesos de fondo. Para leer se usa la base en solo lectura; para escribir, el propio backend (ver CLI y herramientas).

El detalle de cada invariante, con su porqué, vive como decisión registrada en el repositorio (ver Convenciones).

Despliegue

La web y el manual se publican en Vercel al fusionar a la rama principal del Monorepo; cada rama de la web tiene además su vista previa. Esta documentación se construye y se valida en cada PR. Después de desplegar la web se corre la revisión rápida humo de la CLI de la web.
El backend se despliega en Render desde su repositorio: cada PR que entra a su rama principal dispara un despliegue que tarda unos minutos y reinicia el servicio. Antes de probar un arreglo en producción se espera a que quede vivo (yarn -s boost ops deploys esperar).
No hay migraciones automáticas. Los cambios de base de datos se escriben a mano, con su reversa, se ensayan y se aplican antes del despliegue que los necesita.