Saltar a contenido

ADR 0002 — Integration Layer modular con adaptador Shopify

  • Estado: Aceptada para la fase fundacional
  • Fecha: 2026-08-31
  • Decisión irreversible Shopify: ninguna
  • Informe base: Auditoría técnica Shopify

Contexto

TimeLiber es la plataforma principal. Los comercios deben conectar Shopify y, después, otros proveedores sin duplicar usuarios, organizaciones, políticas, datos ni automatizaciones. Existe además una app Shopify de desarrollo llamada TimeLiber Connect, pero su código todavía no está disponible dentro del alcance auditado.

Decisión

Crear un bounded context integrations dentro del backend de TimeLiber Commerce. Cada proveedor se implementará mediante un adaptador detrás de contratos internos. Shopify será el primer adaptador.

TimeLiber Connect será una superficie delgada para las obligaciones específicas de Shopify —instalación, launch embebido, App Bridge y obtención/renovación oficial de tokens— y se comunicará con Commerce mediante HTTP autenticado. No será dueño de usuarios TimeLiber, organizaciones, proyecciones comerciales ni automatizaciones.

En la primera etapa, frontend, API y callbacks públicos usarán commerce.timeliber.com.co con routing por path. No se crea todavía un microservicio ni un subdominio adicional.

Límites

Commerce posee

  • relación entre organization_id y cuentas externas;
  • intents de conexión y autorización TimeLiber;
  • ciphertext y lifecycle de credenciales del proveedor;
  • webhook inbox, jobs, proyecciones y auditoría tenant-bound;
  • capacidades, RLS y emisión de eventos internos;
  • UI principal de Integraciones.

TimeLiber Connect posee

  • configuración de la Shopify App;
  • superficie embebida mínima y App Bridge;
  • autenticación/instalación Shopify mediante mecanismos oficiales;
  • entrega segura de la identidad de instalación al contrato de Commerce.

No posee ninguno de los dos

  • credenciales o tablas de PulseCommerce;
  • modelos importados desde otras verticales;
  • envío autónomo de WhatsApp sin política, consentimiento y aprobación;
  • selección automática de Public/Custom Distribution.

Contrato inicial

El límite HTTP deberá transportar identificadores opacos, estado de instalación y material cifrable únicamente sobre red autenticada. Nunca devolverá access tokens al navegador. La operación de vinculación exige intent de un solo uso, expiración corta, usuario TimeLiber autenticado y verificación de membresía.

Los eventos internos usarán un envelope común con event_id, organization_id, provider, event_type, occurred_at, schema_version, correlation_id y payload mínimo. El contrato se versionará antes de integrar Meta u otro proveedor.

Consecuencias

Positivas

  • reutiliza auth, tenancy, RLS e infraestructura de Commerce;
  • evita convertir el template Shopify en una segunda plataforma;
  • permite extraer el bounded context sin cambiar casos de uso;
  • prepara Meta/CRM/pagos sin crear una abstracción universal prematura.

Costes

  • requiere un contrato explícito entre dos runtimes;
  • exige manejar consistencia, idempotencia y rotación de tokens;
  • la experiencia Shopify embebida y la UI principal deben mantenerse coherentes.

Criterios para extraer un servicio

Se evaluará integrations.timeliber.com.co sólo si aparecen al menos dos de estas condiciones:

  • despliegue o escalado independiente requerido por carga de webhooks/workers;
  • más de dos proveedores con ciclos de release distintos;
  • aislamiento de fallos/secretos imposible dentro del proceso Commerce;
  • equipo propietario y SLO independientes;
  • límites de recursos medidos, no supuestos.

Gates antes de código Shopify

  • código real de TimeLiber Connect disponible y auditado;
  • modelo de datos/migración revisado contra RLS;
  • threat model de install/link/refresh/uninstall;
  • decisión explícita de la versión GraphQL estable;
  • ninguna selección irreversible de distribución.