Ecommerce composable
Armi
Liderazgo técnico de una plataforma multi-commerce: Commerce Tools como motor, Checkout y Merchant Center como productos Next.js, dominio en los bordes.
Líder Técnico Fullstack · Armirene · Enero 2024 — Marzo 2026
- Motor de commerce
- Commerce Tools
- Superficies de producto
- Checkout + Merchant Center
- Identidad
- Clerk
Panorama
Armi es una plataforma de ecommerce multi-commerce. Commerce Tools sostiene catálogo, carrito, clientes y órdenes. Los productos que se usan son Checkout y Merchant Center — aplicaciones Next.js con TypeScript, Apollo/GraphQL y un UI kit compartido.
El trabajo era liderar esas superficies: impedir que el motor de commerce posea el modelo de la aplicación, migrar apps legacy hacia un checkout y un admin más limpios, y hacer la entrega repetible con Docker y Kubernetes.
Checkout v2 modela dinero, moneda, dirección y medio de pago como valores de dominio — no como campos de formulario sueltos en estado de React.
Problema
Un stack de commerce composable falla cuando cada pantalla habla con Commerce Tools en su propio dialecto. Catálogo, checkout y admin terminan codificando tres órdenes distintas, tres clientes distintos y ningún lugar para cambiar una regla una sola vez.
El Merchant Center y el Checkout legacy acumularon GraphQL, context y llamadas al SDK hasta que el camino de compra y el de operaciones no podían evolucionar por separado.
Partners y varios commerces (incluido ARMI Partners) necesitan aislamiento en el límite de commerce-id. Tratar “la tienda” como un singleton global no sobrevive a un segundo tenant.
Restricciones
Catálogo, precio, carrito y escrituras de orden que importan comercialmente pasan por Commerce Tools. Los custom types y atributos (por ejemplo preferencias de marketing del cliente) tienen que existir en cada proyecto CT — merchant-center, checkout y entornos no son intercambiables.
La identidad es Clerk. Los usuarios del Merchant Center se resuelven contra custom fields de Commercetools (clerkId) y, cuando está activo, un servicio de usuarios Armi. La aplicación no puede pretender que CT es el identity provider.
Los eventos operativos — como relanzar una orden desde Merchant Center — necesitan un hecho en el bus (RabbitMQ), no una mutación silenciosa de admin, si los sistemas aguas abajo van a ver lo que pasó.
Arquitectura
El checkout de tienda y el Merchant Center son aplicaciones Next.js separadas. Ambas hablan GraphQL/Apollo hacia Commerce Tools y servicios internos. La arquitectura limpia mantiene casos de uso y valores de dominio independientes del SDK de CT.
Checkout v2 es donde esa regla se ve más: Money, Currency, Address y PaymentMethod se modelan en el dominio y luego se adaptan a Commerce Tools. Reemplazar una integración de pago no debería reescribir el carrito.
Un merchant-service es dueño de los registros de commerce (partners, commerce ids). Docker y Kubernetes son el sustrato de entrega — no la arquitectura.
Architecture
Armi — commerce composable
Checkout
Merchant Center
Next.js
Apollo / GraphQL
Dominio
Dinero, orden, dirección
Commerce Tools
Clerk
Merchant service
RabbitMQ
Eventos de orden
Docker
Kubernetes
Checkout y Merchant Center como bordes de producto. Commerce Tools es dueño del estado comercial. Clerk es dueño de la identidad. RabbitMQ transporta hechos operativos como el relanzamiento de una orden.
Decisiones clave
Experiencia personal
Commerce Tools como motor, no como aplicación
CT sostiene el estado comercial. Checkout y Merchant Center sostienen el producto. Los tipos del vendor se quedan en adaptadores para que un custom field en CT no reescriba el modelo de compra.
Experiencia personal
Checkout v2 como dominio, no como wizard de formularios
Dinero, moneda, dirección y medio de pago son valores que el dominio puede defender. Eso convierte tax, shipping e integraciones de pago en reemplazos en lugar de reescrituras.
Experiencia personal
Separar Merchant Center y Checkout
Operaciones y compra no comparten tren de release ni un UI shell. Comparten contratos y el motor de commerce. Las apps legacy en armi/apps/ son el sistema que se deja atrás.
Experiencia personal
Emitir hechos cuando operaciones cambian una orden
Relanzar una orden desde Merchant Center publica un evento para que la trazabilidad no quede atrapada en un click de admin. Los competing consumers solo sirven si ese trabajo se puede particionar.
Trade-offs
Se ganó
Un motor de commerce que puede servir más de un storefront, y apps de producto que pueden cambiar sin esperar el deploy de un monolito. Pago e identidad se quedan reemplazables en el adaptador.
Se sacrificó
Cada atributo custom tiene que existir en cada proyecto de Commerce Tools. El drift entre entornos (dev / staging / prod) se vuelve un bug de producto. La comodidad de GraphQL puede ocultar cuántas llamadas a CT hace una página.
Experiencia personal
Tecnologías
Resultados
Checkout y Merchant Center son los bordes de producto sobre Commerce Tools, con Clerk para identidad y un merchant-service para registros de commerce/partners.
Checkout v2 lleva un dominio explícito para dinero y pago en lugar de un único árbol de estado de formulario. Acciones operativas como el relanzamiento de una orden dejan un evento, no solo una mutación.
No se publican aquí cifras de conversión ni de latencia.
Lecciones
El commerce composable falla en los bordes: pagos, inventario, identidad y los custom types que olvidaste crear en staging. Trata esos bordes como adaptadores con contratos.
Una página GraphQL que hace fan-out a Commerce Tools sigue siendo un presupuesto de latencia. La query no es la arquitectura.
Kubernetes no arregla un checkout que no puede explicar su propio dinero. Modela la compra primero; agenda el proceso después.