Unchained Engine
Motor de comercio electrónico con servidor MCP integrado
Documentación
Unchained Engine
Licenciado bajo EUPL 1.2
Unchained Engine es una plataforma de comercio electrónico modular, API-first, construida como un monorepo con npm workspaces. Proporciona una solución completa para construir aplicaciones de comercio electrónico personalizadas con APIs GraphQL, arquitectura de plugins extensible y soporte para casos de uso modernos como suscripciones, cotizaciones y productos tokenizados.
Ver Documentación
Inicio Rápido
Requisitos Previos
- Node.js >=26 (consulta .nvmrc para la versión de desarrollo)
- MongoDB 4.4+ (o usa MongoDB Memory Server para desarrollo)
Crear un Nuevo Proyecto
npm init @unchainedshop
Luego navega a http://localhost:4010/ para abrir la interfaz de administración y configurar tu cuenta de administrador en el primer inicio.
Ejecutar IA Local para Copilot
Los requisitos de hardware dependen del modelo, la cuantización y el tamaño del contexto. Para un servidor local compatible con OpenAI, consulta la guía de configuración de Copilot.
llama-server -hf ggml-org/gpt-oss-20b-GGUF --ctx-size 0 --jinja -ub 2048 -b 2048
Arquitectura de Paquetes
Unchained Engine está organizado en una estructura jerárquica:
platform → Highest level orchestration, combines all packages
↓
api → GraphQL API layer with Express/Fastify adapters
↓
core → Business logic coordination, integrates all core-* modules
↓
core-* → Domain-specific modules (users, products, orders, etc.)
↓
infrastructure → Base utilities (mongodb, events, logger, utils, roles)
Paquetes
Plataforma y API
| Paquete | Descripción |
|---|---|
| @unchainedshop/platform | Paquete completo del motor: punto de entrada principal que combina api, core, plugins e infraestructura |
| @unchainedshop/api | API GraphQL con adaptadores Express/Fastify y servidor MCP para integraciones de IA |
| @unchainedshop/core | Orquestación central con servicios de negocio, directores e importación masiva |
Módulos de Dominio Central
Módulos de lógica de negocio para funcionalidad de comercio electrónico:
| Paquete | Descripción |
|---|---|
| @unchainedshop/core-products | Gestión de productos con precios, medios, reseñas y variaciones |
| @unchainedshop/core-orders | Ciclo de vida de pedidos, incluyendo posiciones, pagos, entregas y descuentos |
| @unchainedshop/core-users | Cuentas de usuario, autenticación, perfiles y soporte WebAuthn |
| @unchainedshop/core-payment | Gestión de proveedores de pago y credenciales |
| @unchainedshop/core-delivery | Gestión de proveedores de entrega y métodos de envío |
| @unchainedshop/core-assortments | Gestión de categorías con estructuras jerárquicas |
| @unchainedshop/core-filters | Filtrado de productos y búsqueda facetada |
| @unchainedshop/core-warehousing | Inventario, gestión de stock y sustitutos de tokens |
| @unchainedshop/core-enrollments | Gestión de suscripciones/inscripciones |
| @unchainedshop/core-quotations | Solicitudes de cotización y flujos de propuestas |
| @unchainedshop/core-bookmarks | Funcionalidad de marcadores/listas de deseos del usuario |
| @unchainedshop/core-files | Almacenamiento de metadatos de archivos y gestión de URLs |
| @unchainedshop/core-events | Persistencia del historial de eventos y analítica |
| @unchainedshop/core-worker | Cola de trabajos en segundo plano y procesamiento |
| @unchainedshop/core-countries | Gestión de países con códigos ISO |
| @unchainedshop/core-currencies | Gestión de monedas y soporte blockchain |
| @unchainedshop/core-languages | Gestión de idiomas para i18n |
Infraestructura
Utilidades fundamentales utilizadas en todas las capas:
| Paquete | Descripción |
|---|---|
| @unchainedshop/mongodb | Abstracción de base de datos MongoDB con utilidades y compatibilidad con DocumentDB |
| @unchainedshop/events | Abstracción de emisor de eventos con adaptadores Node.js, Redis y EventBridge |
| @unchainedshop/logger | Registro de alto rendimiento con formatos JSON/legibles |
| @unchainedshop/utils | Utilidades comunes, ayudantes de localización y criptografía |
| @unchainedshop/roles | Sistema de control de acceso basado en roles (RBAC) |
| @unchainedshop/shared | Configuración TypeScript compartida para paquetes del workspace |
Extensiones
| Paquete | Descripción |
|---|---|
| @unchainedshop/plugins | Colección oficial de plugins para pagos, entregas, precios y más |
| @unchainedshop/ticketing | Emisión de entradas para eventos: emisor de entradas, control de acceso, cancelaciones y rutas para tus renderizadores de PDF y pases de cartera |
Interfaz de Administración
| Paquete | Descripción |
|---|---|
| admin-ui | Interfaz de administración Next.js para gestionar la plataforma de comercio electrónico |
Ejemplos
| Ejemplo | Descripción |
|---|---|
| Kitchensink (Fastify) | Ejemplo completo con Fastify, todos los plugins, extensiones de interfaz de administración e integración de IA |
| Kitchensink (Express) | Ejemplo completo con Express, servidor MCP e integración de IA |
| Ticketing | Emisión de entradas para eventos con emisor de entradas, personal de acceso y validación de ventas |
| Minimal | Ejemplo de configuración mínima |
| OIDC | Ejemplo de autenticación OpenID Connect |
Arquitectura de Plugins
Unchained utiliza un patrón Director/Adaptador para la extensibilidad. Los directores gestionan colecciones de adaptadores que implementan comportamientos específicos.
Directores Disponibles
| Director | Propósito | Ejemplos de Adaptadores |
|---|---|---|
PaymentDirector | Procesamiento de pagos | Stripe, Datatrans, Factura |
DeliveryDirector | Envío/entrega | Correo, Recogida, Digital |
WarehousingDirector | Gestión de inventario | Tienda, ETH Minter |
WorkerDirector | Trabajos en segundo plano | Email, SMS, Solicitud HTTP |
FilterDirector | Búsqueda de productos | Igualdad estricta, Búsqueda local |
ProductPricingDirector | Precios de productos | Precio de catálogo, Descuentos |
OrderPricingDirector | Totales de pedidos | Artículos, Entrega, Pago |
MessagingDirector | Notificaciones | Plantillas de email, SMS |
Consulta el README del Core para documentación detallada sobre la creación de adaptadores personalizados.
Plugins Disponibles
El paquete @unchainedshop/plugins incluye:
Pago
- Stripe, Datatrans, Saferpay, PostFinance Checkout
- Payrexx, Cryptopay, Apple IAP
- Factura (estándar y prepago)
Entrega
- Correo (envío manual), Recogida en tienda, Entrega basada en mensajes
Precios
- Precios de catálogo de productos, Conversión de moneda, Cálculo de impuestos (Suiza, UE, Reino Unido, EE. UU.)
- Descuentos a nivel de pedido y de producto
Almacenamiento de Archivos
- MongoDB GridFS, almacenamiento compatible con MinIO/S3
Trabajadores
- Email (Nodemailer), SMS (Twilio, Bulkgate), Notificaciones push
- Actualizaciones de tipos de cambio (ECB, Coinbase), Importación masiva
Eventos
- Node.js EventEmitter, Redis pub/sub, AWS EventBridge
Desarrollo
Comandos
npm install # Install all dependencies
npm run dev # Start development with hot-reload
npm run build # Build all packages
npm test # Run all tests
npm run lint # Lint and fix code
Pruebas
npm run test:run:unit # Run unit tests only
npm run test:run:integration # Run integration tests
node --test path/to/test.ts # Run a single test file
Estructura del Proyecto
unchained/
├── packages/ # All npm packages
│ ├── platform/ # Main entry point
│ ├── api/ # GraphQL API
│ ├── core/ # Business logic orchestration
│ ├── core-*/ # Domain modules
│ ├── plugins/ # Official plugins
│ ├── ticketing/ # Ticketing extension
│ └── ... # Infrastructure packages
├── examples/ # Example implementations
│ ├── kitchensink/ # Full-featured example
│ ├── minimal/ # Minimal setup
│ └── ...
└── tests/ # Integration tests
Guía de Migración
Consulta MIGRATION.md para instrucciones de actualización entre versiones principales.
Integración con Claude Code
La habilidad de actualización guía a los agentes a través de la guía de migración, el registro de cambios y los ejemplos para tu versión objetivo.
Seguridad y Cumplimiento
Unchained Engine está diseñado para su implementación en entornos sensibles a la seguridad, incluidos contextos bancarios, gubernamentales y empresariales.
Cumplimiento
| Estándar | Estado | Notas |
|---|---|---|
| PCI DSS | Dependiente de la implementación | Las integraciones de pago utilizan tokens del proveedor; evalúa el flujo de pago completo |
| ISO 27001 / FINMA / NIS2 | Controles técnicos | El control de acceso y los eventos de auditoría pueden respaldar los controles organizativos |
| FIPS 140-3 | Dependiente de la implementación | Valida el runtime y cada integración de autenticación/pago habilitada |
Estándares Criptográficos
- Hash de Contraseñas: PBKDF2-SHA512 con 300,000 iteraciones
- Seguridad de Tokens: Hash SHA-256, generación criptográficamente aleatoria
- Tokens de Inicio de Sesión: JWT firmados con HS256 con una vida útil predeterminada de una hora
- Firmas de Pago: HMAC-SHA-256/512
Modo FIPS 140-3
Para implementaciones que requieren FIPS, verifica el runtime y todas las integraciones habilitadas. Consulta Configuración FIPS para los requisitos del runtime y los pasos de verificación.
Endurecimiento de la API (Protección contra Denegación de Servicio)
La API GraphQL no impone límites de complejidad de consultas, profundidad, número de alias o límites de tasa de forma predeterminada. Unchained es un motor headless integrado en tu propio proceso de servidor, por lo que dónde y cómo se aplican estas protecciones perimetrales es una decisión de implementación que pertenece al integrador: los umbrales apropiados dependen de tus extensiones de esquema, perfil de tráfico e infraestructura (CDN, WAF, puerta de enlace API, proxy inverso).
El acceso anónimo está habilitado de forma predeterminada para consultas de tienda de solo lectura (por ejemplo, assortments, products, filters, languages, currencies, countries, search). Debido a que GraphQL permite que una sola solicitud agrupe muchos campos con alias, una consulta sin límites puede expandirse en muchas operaciones de base de datos. Limitar esto es responsabilidad del operador.
Capas recomendadas:
-
Validación de consultas (en proceso). Los plugins de GraphQL Yoga y las reglas de validación se reenvían directamente a través de
startPlatform/startAPIServeral servidor Yoga subyacente. Por ejemplo, usando GraphQL Armor:import { startPlatform } from '@unchainedshop/platform'; import { maxAliasesPlugin } from '@escape.tech/graphql-armor-max-aliases'; import { maxDepthPlugin } from '@escape.tech/graphql-armor-max-depth'; import { maxTokensPlugin } from '@escape.tech/graphql-armor-max-tokens'; await startPlatform({ // ...your options plugins: [ maxAliasesPlugin({ n: 15 }), maxDepthPlugin({ n: 10 }), maxTokensPlugin({ n: 1000 }), ], }); -
Límites de tasa y tamaño de solicitud (en el perímetro). Aplica límites de tasa por IP/token y límites de tamaño de cuerpo en tu proxy inverso, puerta de enlace API o WAF (por ejemplo, nginx
limit_req, Cloudflare, AWS WAF). Mantén el tráfico anónimo con un presupuesto más estricto que el tráfico autenticado. -
Límites de paginación. Si expones resolvers de listas personalizados, limita
limit/ paginación en el lado del servidor.
Consulta SECURITY.md para documentación de seguridad completa, detalles de cumplimiento y recomendaciones de implementación.
Recursos
Contribuciones
Consulta nuestras Pautas de Contribución.
Código de Conducta
Consulta nuestro Código de Conducta del Pacto de Colaboradores.
Licencia
EUPL-1.2