Unchained Engine
Motor de Comércio Eletrônico com Servidor MCP integrado
Documentação
Unchained Engine
Licenciado sob a EUPL 1.2
Unchained Engine é uma plataforma de e-commerce modular, API-first, construída como um monorepo com npm workspaces. Ela fornece uma solução completa para construir aplicações de e-commerce personalizadas com APIs GraphQL, arquitetura de plugins extensível e suporte para casos de uso modernos como assinaturas, cotações e produtos tokenizados.
Ver Documentação
Início Rápido
Pré-requisitos
- Node.js >=26 (veja .nvmrc para a versão de desenvolvimento)
- MongoDB 4.4+ (ou use MongoDB Memory Server para desenvolvimento)
Criar um Novo Projeto
npm init @unchainedshop
Em seguida, navegue até http://localhost:4010/ para abrir a interface de administração e configurar sua conta de administrador na primeira execução.
Executar IA Local para o Copilot
Os requisitos de hardware dependem do modelo, quantização e tamanho do contexto. Para um servidor local compatível com OpenAI, veja o guia de configuração do Copilot.
llama-server -hf ggml-org/gpt-oss-20b-GGUF --ctx-size 0 --jinja -ub 2048 -b 2048
Arquitetura de Pacotes
O Unchained Engine é organizado em uma estrutura hierá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)
Pacotes
Plataforma e API
| Pacote | Descrição |
|---|---|
| @unchainedshop/platform | Pacote completo do motor - ponto de entrada principal que combina api, core, plugins e infraestrutura |
| @unchainedshop/api | API GraphQL com adaptadores Express/Fastify e servidor MCP para integrações de IA |
| @unchainedshop/core | Orquestração central com serviços de negócios, diretores e importação em massa |
Módulos Centrais de Domínio
Módulos de lógica de negócios para funcionalidades de e-commerce:
| Pacote | Descrição |
|---|---|
| @unchainedshop/core-products | Gerenciamento de produtos com preços, mídia, avaliações e variações |
| @unchainedshop/core-orders | Ciclo de vida do pedido, incluindo posições, pagamentos, entregas e descontos |
| @unchainedshop/core-users | Contas de usuário, autenticação, perfis e suporte a WebAuthn |
| @unchainedshop/core-payment | Gerenciamento de provedores de pagamento e credenciais |
| @unchainedshop/core-delivery | Gerenciamento de provedores de entrega e métodos de envio |
| @unchainedshop/core-assortments | Gerenciamento de categorias com estruturas hierárquicas |
| @unchainedshop/core-filters | Filtragem de produtos e busca facetada |
| @unchainedshop/core-warehousing | Inventário, gerenciamento de estoque e substitutos de token |
| @unchainedshop/core-enrollments | Gerenciamento de assinaturas/inscrições |
| @unchainedshop/core-quotations | Solicitações de cotação e fluxos de trabalho de propostas |
| @unchainedshop/core-bookmarks | Funcionalidade de favoritos/lista de desejos do usuário |
| @unchainedshop/core-files | Armazenamento de metadados de arquivos e gerenciamento de URLs |
| @unchainedshop/core-events | Persistência de histórico de eventos e análises |
| @unchainedshop/core-worker | Fila de tarefas em segundo plano e processamento |
| @unchainedshop/core-countries | Gerenciamento de países com códigos ISO |
| @unchainedshop/core-currencies | Gerenciamento de moedas e suporte a blockchain |
| @unchainedshop/core-languages | Gerenciamento de idiomas para i18n |
Infraestrutura
Utilitários fundamentais usados em todas as camadas:
| Pacote | Descrição |
|---|---|
| @unchainedshop/mongodb | Abstração de banco de dados MongoDB com utilitários e compatibilidade com DocumentDB |
| @unchainedshop/events | Abstração de emissor de eventos com adaptadores Node.js, Redis e EventBridge |
| @unchainedshop/logger | Registro de alto desempenho com formatos JSON/legíveis |
| @unchainedshop/utils | Utilitários comuns, auxiliares de localidade e auxiliares criptográficos |
| @unchainedshop/roles | Sistema de controle de acesso baseado em funções (RBAC) |
| @unchainedshop/shared | Configuração TypeScript compartilhada para pacotes do workspace |
Extensões
| Pacote | Descrição |
|---|---|
| @unchainedshop/plugins | Coleção oficial de plugins para pagamento, entrega, preços e mais |
| @unchainedshop/ticketing | Emissão de ingressos para eventos: emissor de ingressos, controle de portão, cancelamentos e rotas para seus renderizadores de PDF e passes de carteira |
Interface de Administração
| Pacote | Descrição |
|---|---|
| admin-ui | Interface de administração Next.js para gerenciar a plataforma de e-commerce |
Exemplos
| Exemplo | Descrição |
|---|---|
| Kitchensink (Fastify) | Exemplo completo com Fastify, todos os plugins, extensões da interface de administração e integração de IA |
| Kitchensink (Express) | Exemplo completo com Express, servidor MCP e integração de IA |
| Ticketing | Emissão de ingressos para eventos com emissor de ingressos, equipe de portão e validação de vendas |
| Minimal | Exemplo de configuração mínima |
| OIDC | Exemplo de autenticação OpenID Connect |
Arquitetura de Plugins
O Unchained usa um padrão Diretor/Adaptador para extensibilidade. Os diretores gerenciam coleções de adaptadores que implementam comportamentos específicos.
Diretores Disponíveis
| Diretor | Propósito | Exemplos de Adaptadores |
|---|---|---|
PaymentDirector | Processamento de pagamentos | Stripe, Datatrans, Invoice |
DeliveryDirector | Envio/entrega | Post, Pickup, Digital |
WarehousingDirector | Gerenciamento de inventário | Store, ETH Minter |
WorkerDirector | Tarefas em segundo plano | Email, SMS, HTTP Request |
FilterDirector | Busca de produtos | Strict Equal, Local Search |
ProductPricingDirector | Preços de produtos | Catalog Price, Discounts |
OrderPricingDirector | Totais de pedidos | Items, Delivery, Payment |
MessagingDirector | Notificações | Modelos de email, SMS |
Veja o README do Core para documentação detalhada sobre como criar adaptadores personalizados.
Plugins Disponíveis
O pacote @unchainedshop/plugins inclui:
Pagamento
- Stripe, Datatrans, Saferpay, PostFinance Checkout
- Payrexx, Cryptopay, Apple IAP
- Invoice (padrão e pré-pago)
Entrega
- Post (envio manual), retirada na loja, entrega baseada em mensagens
Preços
- Preços de catálogo de produtos, conversão de moeda, cálculo de impostos (Suíça, UE, Reino Unido, EUA)
- Descontos em nível de pedido e de produto
Armazenamento de Arquivos
- MongoDB GridFS, armazenamento compatível com MinIO/S3
Trabalhadores
- Email (Nodemailer), SMS (Twilio, Bulkgate), notificações push
- Atualizações de taxas de câmbio (ECB, Coinbase), importação em massa
Eventos
- Node.js EventEmitter, Redis pub/sub, AWS EventBridge
Desenvolvimento
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
Testes
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
Estrutura do Projeto
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
Guia de Migração
Veja MIGRATION.md para instruções de atualização entre versões principais.
Integração com Claude Code
A habilidade de atualização orienta agentes pelo guia de migração, changelog e exemplos para sua versão de destino.
Segurança e Conformidade
O Unchained Engine é projetado para implantação em ambientes sensíveis à segurança, incluindo contextos bancários, governamentais e empresariais.
Conformidade
| Padrão | Status | Notas |
|---|---|---|
| PCI DSS | Dependente da implantação | Integrações de pagamento usam tokens do provedor; avalie o fluxo completo de pagamento |
| ISO 27001 / FINMA / NIS2 | Controles técnicos | Controle de acesso e eventos de auditoria podem apoiar controles organizacionais |
| FIPS 140-3 | Dependente da implantação | Valide o runtime e cada integração de autenticação/pagamento habilitada |
Padrões Criptográficos
- Hash de Senhas: PBKDF2-SHA512 com 300.000 iterações
- Segurança de Tokens: Hash SHA-256, geração criptograficamente aleatória
- Tokens de Login: JWTs assinados com HS256 com vida útil padrão de uma hora
- Assinaturas de Pagamento: HMAC-SHA-256/512
Modo FIPS 140-3
Para implantações que exigem FIPS, verifique o runtime e todas as integrações habilitadas. Veja configuração FIPS para os requisitos de runtime e etapas de verificação.
Endurecimento da API (Proteção contra Negação de Serviço)
A API GraphQL não impõe limites de complexidade de consulta, profundidade, contagem de aliases ou limite de taxa por padrão. O Unchained é um motor headless incorporado ao seu próprio processo de servidor, portanto, onde e como essas proteções de borda são aplicadas é uma decisão de implantação que pertence ao integrador — os limites apropriados dependem das extensões do seu esquema, perfil de tráfego e infraestrutura (CDN, WAF, gateway de API, proxy reverso).
O acesso anônimo é habilitado por padrão para consultas somente leitura da loja (por exemplo, assortments, products, filters, languages, currencies, countries, search). Como o GraphQL permite que uma única solicitação agrupe muitos campos com alias, uma consulta sem limites pode se expandir em muitas operações de banco de dados. Limitar isso é responsabilidade do operador.
Camadas recomendadas:
-
Validação de consulta (no processo). Plugins e regras de validação do GraphQL Yoga são encaminhados diretamente por
startPlatform/startAPIServerpara o servidor Yoga subjacente. Por exemplo, 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 }), ], }); -
Limite de taxa e limites de tamanho de solicitação (na borda). Aplique limites de taxa por IP/token e limites de tamanho de corpo no seu proxy reverso, gateway de API ou WAF (por exemplo, nginx
limit_req, Cloudflare, AWS WAF). Mantenha o tráfego anônimo com um orçamento mais restrito do que o tráfego autenticado. -
Limites de paginação. Se você expor resolvedores de lista personalizados, limite
limit/ paginação no lado do servidor.
Veja SECURITY.md para documentação completa de segurança, detalhes de conformidade e recomendações de implantação.
Recursos
Contribuindo
Consulte nossas Diretrizes de Contribuição.
Código de Conduta
Veja nosso Código de Conduta do Contributor Covenant.
Licença
EUPL-1.2