ARCH-01 / HEXAGONAL_ARCHITECTURE / DESACOPLAMIENTO DE PROVEEDOR

Capas del Backend, Provider Layer & Extensibilidad Futura

Esta especificación describe la separación entre el Núcleo de Dominio de Innovia y los adaptadores de mensajería externa, aplicando el patrón de puertos y adaptadores (Arquitectura Hexagonal).

PRINCIPIO 1

Innovia es Sistema Maestro

Nuestra base de datos PostgreSQL mantiene el estado autoritativo de Tenants, Líneas, Campañas, Mensajes y Métricas. Kapso es el motor de despacho, no la fuente de verdad.

PRINCIPIO 2

Regla Estricta de Desacople

Ningún identificador de Kapso (ej. kps_cust_912), estructura de datos propietaria ni endpoint se expone al Frontend ni a la API Pública.

PRINCIPIO 3

Test de Sustitución Directa

Si mañana se incorpora Gupshup o Meta Cloud API directo, solo se implementa una nueva clase Adapter. El frontend y los clientes externos no requieren ningún cambio.

Mapa de Componentes del Sistema

Flujo de peticiones a través de las capas de seguridad, dominio, orquestación y proveedor

100%

Hexagonal

graph TB subgraph CLIENTS ["Capa de Clientes & Consumidores"] WebApp["Frontend Web Innovia\n(Dashboard Next.js)"] ExtAPI["Sistemas de Clientes\n(CRM, ERP, Facturación)"] end subgraph INGRESS ["Ingreso & Seguridad"] Gateway["Reverse Proxy / API Gateway"] AuthMid["Auth Middleware\n(Session JWT / inn_live_* API Key)"] RateLimiter["Rate Limiter (Redis Token Bucket)"] end CLIENTS --> Gateway Gateway --> AuthMid AuthMid --> RateLimiter subgraph CORE ["Innovia Core Backend Engine"] direction TB TenantSvc["Tenant & User Service"] PhoneSvc["Phone Connection Service"] TemplateSvc["Template Sync & Mapping"] CampaignSvc["Campaign Engine (Orquestador)"] MsgSvc["Transactional Messaging"] EventSvc["Event & Tracking Normalizer"] BillingSvc["Usage Metering & Balance"] end RateLimiter --> CORE subgraph STORAGE ["Capa de Persistencia"] PG[("PostgreSQL\n(Multi-tenant DB)")] RedisQueue[("Redis\n(BullMQ Schedulers & Jobs)")] end CORE --> PG CORE --> RedisQueue subgraph PROVIDER_LAYER ["Provider Abstraction Layer"] ProviderInterface["Interface: MessagingProvider"] KapsoAdapter["KapsoAdapter\n(Implementación Oficial MVP)"] FutureAdapters["Futuros: GupshupAdapter / MetaCloudAdapter"] ProviderInterface --> KapsoAdapter ProviderInterface -.-> FutureAdapters end CampaignSvc --> ProviderInterface MsgSvc --> ProviderInterface PhoneSvc --> ProviderInterface TemplateSvc --> ProviderInterface subgraph EXTERNAL ["Infraestructura Externa"] KapsoAPI["Kapso Platform API"] KapsoWebhooks["Kapso Webhooks Salientes"] MetaCloud["Meta WhatsApp Network"] end KapsoAdapter -->|REST Calls| KapsoAPI KapsoAPI --> MetaCloud KapsoWebhooks -->|HTTP POST| WebhookReceiver["Innovia Webhook Endpoint\n/webhooks/providers/kapso"] WebhookReceiver --> EventSvc EventSvc --> PG

Capa de Abstracción: MessagingProvider Port

Define el contrato unificado sin atar a Innovia al SDK de Kapso

Ver Contratos TypeScript en MD

Onboarding WABA

`createCustomer()`, `createSetupLink()`, `syncPhoneNumbers()`.

Gestión de Plantillas

`syncTemplates(wabaId)` para sincronizar plantillas aprobadas por Meta.

Envíos Transaccionales

`sendTemplateMessage(phoneId, payload)` con retorno de providerMessageId.

Campañas & Webhooks

`createAndExecuteBroadcast()` y `normalizeWebhook()` a enums de Innovia.

Evolución Multi-Proveedor Sin Modificar el Modelo Central

Incorporar Gupshup o Meta Cloud API solo requiere una clase Adapter adicional

100%

flowchart LR A[Core Domain Innovia] --> B[Provider Router / Factory] B -->|Líneas Standard con Managed Billing| C[KapsoAdapter] B -->|Líneas Alto Volumen con Cap| D[GupshupAdapter] B -->|Conexión Enterprise Directa| E[MetaCloudAdapter] C --> Kapso[Kapso Platform] D --> Gupshup[Gupshup API] E --> Meta[Meta Cloud API]