ADR 0001 — Trasplante selectivo desde PulseCommerce
Estado
Aceptado — 2026-08-31
Contexto
PulseCommerce es un repositorio independiente en /home/admin_/software/freelance. Contiene una base relevante para Shopify: FastAPI, React/Vite, autenticación, MFA, organizaciones, RLS, conexiones OAuth, workers, pedidos y pruebas.
TimeLiber Commerce pertenece a otro bounded context operacional y debe cumplir la infraestructura, seguridad y documentación del monorepo. Copiar el repositorio completo también copiaría decisiones específicas de despliegue, redes, cloud, nombres y alcance que no son automáticamente válidas aquí.
El propósito inicial de la nueva vertical es aprender y establecer cimientos. No se necesita decidir de antemano qué porcentaje de PulseCommerce terminará utilizándose.
Decisión
PulseCommerce se tratará como fuente de referencia de sólo lectura. El trasplante se realizará módulo por módulo mediante cuatro decisiones explícitas:
| Clasificación | Uso |
|---|---|
| Reutilizar | El código cumple el estándar TimeLiber y puede conservar comportamiento y pruebas. |
| Adaptar | La lógica es válida, pero infraestructura, contratos o nomenclatura deben cambiar. |
| Reescribir | El concepto sirve, pero conservar la implementación aumenta riesgo o deuda. |
| Descartar | La capacidad no pertenece al alcance o depende de decisiones superadas. |
No se permite copiar el árbol completo y corregirlo después.
Matriz inicial
| Área de PulseCommerce | Decisión inicial | Razón |
|---|---|---|
| Auth, sesiones y MFA | Adaptar | Base madura; debe alinearse con configuración y contratos TimeLiber. |
| Organizaciones y membresías | Reutilizar/adaptar | Encaja con multi-tenancy, sujeto a revisión de nombres y ownership. |
| RLS y autorización | Adaptar | Patrón correcto; debe usar roles y provisioning de infra/. |
| Modelo de conexiones | Adaptar | Es reutilizable, pero debe representar futuros canales sin sobre-generalizar. |
| Shopify OAuth | Adaptar | El flujo y pruebas aportan valor; la app, URLs y secretos serán nuevos. |
| Webhooks y workers | Adaptar | Deben usar Redis y convenciones operativas de TimeLiber. |
| Sincronización de pedidos | Adaptar | Se conserva idempotencia; se revalida contra la versión oficial vigente. |
| Analytics post-product | Descartar por ahora | No sirve al aprendizaje Shopify inicial. |
| Placeholders Meta/WhatsApp | Descartar | No constituyen integración implementada. |
| Frontend auth/onboarding | Adaptar | Puede acelerar el recorrido, pero no define todavía la UX final. |
| Design system visual | Evaluar | Reutilizar sólo piezas accesibles y coherentes con una identidad nueva. |
| GCP Pub/Sub, BigQuery, Cloud Run | Descartar | TimeLiber centraliza estado y operación en infra/; no hay necesidad demostrada. |
| Red Docker aislada | Descartar | La vertical usará timeliber-net y proxy-net conforme al monorepo. |
La matriz se actualizará con evidencia durante el inventario. Una clasificación inicial no autoriza copiar código automáticamente.
Orden de trasplante
- Configuración, base de datos y test harness.
- Identidad, sesiones y MFA.
- Tenancy, membresía, autorización y RLS.
- Conexiones y cifrado.
- Shopify OAuth e instalación.
- Webhooks y workers.
- Pedidos y conciliación.
- Frontend mínimo para recorrer el journey.
Cada paso debe compilar, tener pruebas y actualizar documentación antes de comenzar el siguiente.
Reglas de compatibilidad
- No se modificará
/home/admin_/software/freelance. - No se copiarán
.env, tokens, IDs de Shopify ni archivos generados con secretos. - La aplicación Shopify de TimeLiber Commerce tendrá identidad y configuración propias.
- PostgreSQL será compartido como motor, pero la vertical tendrá base y rol exclusivos.
- Redis usará un namespace o base reservada sin colisiones.
- Los backends serán stateless y se comunicarán con otras verticales sólo por HTTP REST.
- Todo query tenant-scoped contendrá
tenant_id; RLS no sustituye el filtro de aplicación.
Consecuencias
Positivas
- Preserva el aprendizaje y código útil de PulseCommerce.
- Evita heredar infraestructura incompatible.
- Permite cambiar el producto comercial sin perder los cimientos.
- Hace visible qué está probado y qué sólo fue trasladado.
Costes
- El trasplante será más lento que una copia masiva inicial.
- Algunas pruebas deberán reescribirse por cambios de infraestructura.
- Dos implementaciones coexistirán hasta completar la migración selectiva.
Riesgos mitigados
- Copiar secretos o IDs externos.
- Romper aislamiento multi-tenant.
- Confundir código existente con validación del nuevo producto.
- Heredar servicios cloud sin necesidad.
- Acoplar TimeLiber Commerce permanentemente a Shopify.
Gate de revisión
Antes de copiar cada dominio se documentará:
- archivos fuente candidatos;
- dependencias internas y externas;
- pruebas existentes;
- divergencias frente al estándar TimeLiber;
- clasificación final;
- Definition of Done del trasplante.