Arquitectura del Backend

Stack tecnologico

Capa	Tecnologia
Framework	NestJS 11
Lenguaje	TypeScript 5.7
Base de datos	MySQL 8 + TypeORM
Autenticacion	JWT (Passport) + bcrypt
Tiempo real	Socket.IO (2 namespaces)
Almacenamiento	AWS S3 (presigned URLs)
Media	sharp (imagenes) + ffmpeg (audio/video)
Documentos	pdf-lib (generacion de PDFs)
Validacion	class-validator + class-transformer
API docs	Swagger (@nestjs/swagger)

Modulos del sistema

BoostAPI esta organizado en 21 modulos NestJS. Cada modulo encapsula un dominio de negocio.

Modulos de infraestructura

Modulo	Funcion
PulpitoModule (global)	Cache en memoria con stale-while-revalidate, singleflight, invalidacion por tags
CommonModule	Utilidades compartidas: DTOs de paginacion, transformadores, formateo de moneda
MediaStorageModule	Uploads a S3 con presigned URLs, procesamiento de imagenes/audio/video
GlobalSettingsModule	Configuraciones key-value por entidad (empresa)

Modulos de dominio CRM

Modulo	Funcion
AuthModule	Login JWT, cambio de entidad, validacion de credenciales
ZauruModule	Sesion con ERP Zauru: credenciales cifradas, GraphQL, perfiles
UserModule	CRUD de usuarios del CRM
EntitiesModule	CRUD de entidades (empresas/tenants)
PermissionsModule	Registro de permisos, permisos efectivos por usuario
RolesModule	CRUD de roles con asignacion de permisos
EmployeesModule	CRUD de empleados
SubscriptionsModule	Vinculacion usuario/empleado + rol + entidad
RecordsModule	Grupos, Leads, Contactos, Asignaciones de vendedor, Facturas, Pagos (Zauru)
CustomFieldsModule	Campos personalizados: tipos, grupos, campos, valores
CatalogsModule	Proxy a catalogos Zauru (monedas, departamentos, municipios, metodos de pago)
CatalogoModule	Catalogo de productos: items, bundles, stock desde Zauru con cache Pulpito
OrdersModule	Creacion/edicion de pedidos (se envian a Zauru)
QuotesModule	Cotizaciones: CRUD, aprobacion, rechazo, checkout publico, plantillas
OpportunitiesModule	Kanban de oportunidades: funnels, estados, eventos
AgendaModule	Eventos de calendario con sistema de alertas
NotificationsModule	Notificaciones CRUD + push via WebSocket
InteractionsModule	Conversaciones WhatsApp/messaging, ingestion de webhooks, tiempo real
PaymentsModule	Receptor de webhooks de pagos (placeholder)

Patrones arquitectonicos clave

Multi-tenant por entity_id

Casi toda query esta filtrada por entity_id del JWT del usuario autenticado. Una “entidad” representa una empresa en Zauru.

Decorador compuesto de autenticacion

@Authentication('leads.create')

Un solo decorador combina: JWT guard + verificacion de permiso. Si se omite el argumento, solo valida el JWT.

Proxy a Zauru

El CRM no almacena la mayoria de datos operativos (facturas, pagos, productos). Estos se resuelven en tiempo real desde Zauru via REST/GraphQL, con Pulpito como cache.

Doble propiedad de datos

Datos locales (MySQL)	Datos proxy (Zauru)
Grupos, Asignaciones	Facturas, Pagos
Leads (sin zauru_id)	Productos, Stock
Contactos	Monedas, Departamentos
Campos personalizados	Metodos de pago
Cotizaciones, Plantillas	Perfiles de payee
Oportunidades (Kanban)	Pedidos (post-creacion)
Conversaciones	–
Eventos de agenda	–

WebSocket con dos namespaces

• /interactions – eventos de mensajeria en tiempo real
• /notifications – notificaciones push por usuario

Ambos usan JWT para autenticacion via handshake.

Manejo de archivos multipart

Pedidos, cotizaciones y mensajes usan multer en memoria con FileInterceptor/FileFieldsInterceptor. Los archivos se procesan con sharp/ffmpeg o se reenvian a S3/Communications.

Credenciales cifradas

Las API keys de Zauru se almacenan cifradas con AES-256-CBC en la base de datos, usando una clave de encriptacion por entorno.

Diagrama de flujo de un request tipico

1. Request HTTP llega a NestJS
2. Global ValidationPipe valida el body (whitelist + forbidNonWhitelisted)
3. JWT Guard extrae y valida el token Bearer
4. Permission Guard verifica el permiso requerido contra los permisos del usuario
5. Controller recibe el request validado
6. Service ejecuta logica de negocio
   - Si necesita datos de Zauru: Pulpito cache -> Zauru GraphQL/REST
   - Si necesita datos locales: TypeORM -> MySQL
7. Response se devuelve al cliente

Referencia privada: Para ver la implementacion exacta de cada modulo, revisa BoostAPI/src/{modulo}/ en el repositorio.