# Unchained Engine

> Headless, code-first e-commerce SDK for Node.js with GraphQL API, MCP server for AI agents, and Admin UI Copilot.

## About Unchained Engine

Unchained Engine is an open-source, headless, code-first e-commerce SDK for Node.js. It provides a modular architecture where every component can be extended or replaced through a Director/Adapter plugin pattern.

### Package Hierarchy

- **@unchainedshop/platform** — Top-level orchestration, combines all packages
- **@unchainedshop/api** — GraphQL API layer (Express/Fastify adapters, GraphQL Yoga, MCP server)
- **@unchainedshop/core** — Business logic coordination across all domain modules
- **core-*** — Domain modules: orders, products, users, payment, delivery, assortments, filters, enrollments, warehousing, worker, files, events, countries, currencies, languages
- **@unchainedshop/plugins** — Payment, delivery, pricing, and warehousing adapters (Stripe, Datatrans, Cryptopay, etc.)
- **Infrastructure** — mongodb, events, logger, utils, roles, file-upload

### Key Entry Points

- **GraphQL API** — Primary interface for storefront and admin operations
- **MCP Server** — Model Context Protocol server enabling AI agents to manage products, orders, and more
- **Admin UI** — React-based back-office with built-in AI Copilot

### Plugin System

Plugins follow a Director/Adapter pattern: Directors manage collections of Adapters. Adapters are registered explicitly before platform startup. Available presets: base (essential), all (complete), crypto (cryptocurrency).

### Common Operations

- **Products**: CRUD, pricing, media, variations (configurable/bundle/plan types)
- **Orders**: Cart management, checkout, payment & delivery processing, lifecycle hooks
- **Payments**: Pluggable providers (Stripe, Datatrans, Braintree, Apple IAP, Cryptopay, Invoice)
- **Delivery**: Pluggable providers (Post, Send-Message, Stores)
- **Pricing**: Layered pricing pipeline with discount support
- **Assortments**: Hierarchical product categories with filters

## Table of Contents

- [Assortments](https://docs.unchained.shop/docs/admin-ui/assortment): Organize products into hierarchical categories and assortments with filters and sub-assortment support.
- [Authentication](https://docs.unchained.shop/docs/admin-ui/authentication): Configure authentication flows in Unchained including web authentication and email/password registration.
- [Country](https://docs.unchained.shop/docs/admin-ui/country): Add and manage supported countries for your e-commerce store including activation and default currency settings.
- [Currency](https://docs.unchained.shop/docs/admin-ui/currency): Configure supported currencies and cryptocurrency tokens including contract addresses and decimal precision.
- [Delivery provider](https://docs.unchained.shop/docs/admin-ui/delivery-provider): Configure and manage delivery provider plugins for shipping, pickup, and digital delivery methods.
- [Events](https://docs.unchained.shop/docs/admin-ui/events): Browse and inspect system events emitted by Unchained Engine for debugging and audit purposes.
- [Filter](https://docs.unchained.shop/docs/admin-ui/filter): Create and manage product filters and faceted search options for storefront browsing.
- [Language](https://docs.unchained.shop/docs/admin-ui/language): Configure multi-language support for your store by adding and managing locales in the Admin UI.
- [Orders](https://docs.unchained.shop/docs/admin-ui/orders): View and manage orders in the Admin UI including status tracking, payment confirmation, and delivery updates.
- [Overview](https://docs.unchained.shop/docs/admin-ui/overview): Overview of the Unchained Admin UI for managing products, orders, customers, and store configuration.
- [Payment provider](https://docs.unchained.shop/docs/admin-ui/payment-provider): Configure and manage payment provider plugins like Stripe, Datatrans, and Invoice in the Admin UI.
- [Products](https://docs.unchained.shop/docs/admin-ui/products): Manage products in the Admin UI including creation, pricing, media uploads, and product variations.
- [Users](https://docs.unchained.shop/docs/admin-ui/users): Manage customer accounts and guest users in the Admin UI including profiles, order history, and user roles.
- [Warehousing provider](https://docs.unchained.shop/docs/admin-ui/warehousing-provider): Configure warehousing provider plugins to manage inventory, stock levels, and product availability.
- [Work Queue](https://docs.unchained.shop/docs/admin-ui/work-queue): Monitor and manage background tasks and worker jobs in the Unchained work queue system.
- [Admin Copilot Setup](https://docs.unchained.shop/docs/ai-integration/admin-copilot): Set up and use the AI Copilot in the Unchained Admin UI to manage products, orders, and store configuration with natural language.
- [AI Integration FAQ](https://docs.unchained.shop/docs/ai-integration/ai-faq): Frequently asked questions about Unchained Engine AI features — for humans and AI agents alike
- [AI Integration](https://docs.unchained.shop/docs/ai-integration): Overview of Unchained Engine's AI integration surfaces including MCP Server, Admin Copilot, and llms.txt.
- [MCP Server Reference](https://docs.unchained.shop/docs/ai-integration/mcp-server): Reference documentation for the Model Context Protocol (MCP) server that enables AI agents to manage your Unchained store.
- [Architecture](https://docs.unchained.shop/docs/concepts/architecture): Understanding Unchained Engine's layered architecture
- [Authentication](https://docs.unchained.shop/docs/concepts/authentication): Understanding authentication patterns in Unchained Engine
- [Director/Adapter Pattern](https://docs.unchained.shop/docs/concepts/director-adapter-pattern): Understanding Unchained Engine's plugin architecture
- [GraphQL API Reference](https://docs.unchained.shop/docs/concepts/graphql-api): Complete reference for queries, mutations, types, and scalars in the Unchained Engine GraphQL API
- [Core Concepts](https://docs.unchained.shop/docs/concepts): Foundational concepts for understanding Unchained Engine
- [Order Lifecycle](https://docs.unchained.shop/docs/concepts/order-lifecycle): Understanding how orders flow from cart to fulfillment
- [Permissions Reference](https://docs.unchained.shop/docs/concepts/permissions): Complete reference for RBAC permissions, roles, and access control in Unchained Engine
- [Pricing System](https://docs.unchained.shop/docs/concepts/pricing-system): Understanding how prices are calculated in Unchained Engine
- [Docker Deployment](https://docs.unchained.shop/docs/deployment/docker): Deploying Unchained Engine with Docker
- [Deployment](https://docs.unchained.shop/docs/deployment): Deploying Unchained Engine to production
- [Production Checklist](https://docs.unchained.shop/docs/deployment/production-checklist): Pre-launch checklist for Unchained Engine
- [Security](https://docs.unchained.shop/docs/deployment/security): Security features, compliance support, and best practices for Unchained Engine
- [Admin UI Extension](https://docs.unchained.shop/docs/extend/admin-ui): Extending Admin UI
- [Filter](https://docs.unchained.shop/docs/extend/catalog/filter): Customize filter and search
- [Search Behavior](https://docs.unchained.shop/docs/extend/catalog/search-behavior): Learn about the search feature
- [Write Custom Modules](https://docs.unchained.shop/docs/extend/custom-modules): Configure custom modules and services
- [Enrollments](https://docs.unchained.shop/docs/extend/enrollment): Customizing subscription and enrollment handling
- [Event System](https://docs.unchained.shop/docs/extend/events): How to use the built-in Event system
- [Extend the GraphQL API](https://docs.unchained.shop/docs/extend/graphql): Extending the schema to hold custom types
- [Carts](https://docs.unchained.shop/docs/extend/order-fulfilment/carts): Learn about how carts works
- [Write a Delivery Provider Plugin](https://docs.unchained.shop/docs/extend/order-fulfilment/fulfilment-plugins/delivery): Customize delivery
- [Write a Payment Provider Plugin](https://docs.unchained.shop/docs/extend/order-fulfilment/fulfilment-plugins/payment): Guide to writing a custom payment provider plugin for Unchained Engine with the PaymentAdapter interface.
- [Write a Warehousing Provider Plugin](https://docs.unchained.shop/docs/extend/order-fulfilment/fulfilment-plugins/warehousing): Customize warehousing
- [Fulfilment Process](https://docs.unchained.shop/docs/extend/order-fulfilment): Learn about how carts transition to orders and finalize
- [Delivery Pricing](https://docs.unchained.shop/docs/extend/pricing/delivery-pricing): Custom delivery pricing adapters
- [Order Discounts](https://docs.unchained.shop/docs/extend/pricing/order-discounts): Custom discount adapters for orders
- [Payment Pricing](https://docs.unchained.shop/docs/extend/pricing/payment-pricing): Custom payment pricing adapters
- [Product Pricing](https://docs.unchained.shop/docs/extend/pricing/product-pricing): Custom product pricing adapters
- [Quotations](https://docs.unchained.shop/docs/extend/quotation): Customizing quotation
- [Work Queue](https://docs.unchained.shop/docs/extend/worker): Add custom background workers
- [Building a Storefront](https://docs.unchained.shop/docs/guides/building-a-storefront): Guide to building a frontend storefront with Unchained Engine
- [Bulk Import](https://docs.unchained.shop/docs/guides/bulk-import): Import large amounts of data from PIM/ERP systems
- [Checkout Implementation](https://docs.unchained.shop/docs/guides/checkout-implementation): Complete guide to implementing checkout with Unchained Engine
- [Contributing](https://docs.unchained.shop/docs/guides/contributing): Development workflow, code standards, and how to contribute to Unchained Engine
- [Custom Pricing](https://docs.unchained.shop/docs/guides/custom-pricing): Implement custom pricing logic with pricing adapters
- [File Uploads](https://docs.unchained.shop/docs/guides/file-uploads): Managing file uploads with MinIO or S3-compatible storage
- [Developer Guides](https://docs.unchained.shop/docs/guides): Practical guides for building with Unchained Engine
- [Multi-Currency Setup](https://docs.unchained.shop/docs/guides/multi-currency-setup): Configure multiple currencies in Unchained Engine
- [Multi-Language Setup](https://docs.unchained.shop/docs/guides/multi-language-setup): Configure multiple languages in Unchained Engine
- [Payment Integration](https://docs.unchained.shop/docs/guides/payment-integration): Guide to integrating payment providers with Unchained Engine
- [Search and Filtering](https://docs.unchained.shop/docs/guides/search-and-filtering): Implementing product search and filtering with Unchained Engine
- [Seed Data](https://docs.unchained.shop/docs/guides/seed-data): Bootstrap a fresh Unchained Engine instance with initial data
- [Express vs Fastify Setup](https://docs.unchained.shop/docs/guides/server-setup): Choose and configure Express or Fastify as your HTTP server framework
- [Testing](https://docs.unchained.shop/docs/guides/testing): How to test custom plugins, modules, and integrations
- [Event Ticketing Setup](https://docs.unchained.shop/docs/guides/ticketing-setup): Configure event ticketing with PDF tickets, Apple Wallet, and Google Wallet passes
- [Unchained Engine Documentation](https://docs.unchained.shop/docs/): Open-source headless e-commerce framework for Node.js
- [Migrations](https://docs.unchained.shop/docs/migrations): Upgrading between major versions of Unchained Engine
- [Enable AI Copilot in Unchained Admin UI](https://docs.unchained.shop/docs/platform-configuration/enable-copilot): Steps to activate the AI Copilot feature in the Unchained Admin UI for natural-language store management.
- [Environment Variables](https://docs.unchained.shop/docs/platform-configuration/environment-variables): Complete reference of all environment variables for configuring Unchained Engine core, API, file uploads, and worker settings.
- [Platform Configuration](https://docs.unchained.shop/docs/platform-configuration): Configure Unchained Engine boot options, module settings, plugin registration, and runtime behavior.
- [Messaging](https://docs.unchained.shop/docs/platform-configuration/messaging): Configure email and SMS messaging templates for notifications, order confirmations, and custom alerts.
- [Assortments Module](https://docs.unchained.shop/docs/platform-configuration/modules/assortments): Product categorization and hierarchical organization
- [Bookmarks Module](https://docs.unchained.shop/docs/platform-configuration/modules/bookmarks): User favorites and wishlist functionality
- [Countries Module](https://docs.unchained.shop/docs/platform-configuration/modules/countries): Country configuration and management
- [Currencies Module](https://docs.unchained.shop/docs/platform-configuration/modules/currencies): Currency configuration and management
- [Delivery Module](https://docs.unchained.shop/docs/platform-configuration/modules/delivery): Delivery provider configuration and filtering
- [Enrollments Module](https://docs.unchained.shop/docs/platform-configuration/modules/enrollments): Subscription and recurring order management
- [Events Module](https://docs.unchained.shop/docs/platform-configuration/modules/events): Event history and audit trail
- [Files Module](https://docs.unchained.shop/docs/platform-configuration/modules/files): File storage and URL transformation
- [Filters Module](https://docs.unchained.shop/docs/platform-configuration/modules/filters): Product filtering and faceted search configuration
- [Core Modules](https://docs.unchained.shop/docs/platform-configuration/modules): Overview of Unchained Engine core modules and configuration
- [Languages Module](https://docs.unchained.shop/docs/platform-configuration/modules/languages): Language configuration and management
- [Orders Module](https://docs.unchained.shop/docs/platform-configuration/modules/orders): Order lifecycle and cart management
- [Payment Module](https://docs.unchained.shop/docs/platform-configuration/modules/payment): Payment provider configuration and filtering
- [Products Module](https://docs.unchained.shop/docs/platform-configuration/modules/products): Product catalog management and configuration
- [Quotations Module](https://docs.unchained.shop/docs/platform-configuration/modules/quotations): Quote request and proposal management
- [Users Module](https://docs.unchained.shop/docs/platform-configuration/modules/users): User management, authentication, and profile configuration
- [Warehousing Module](https://docs.unchained.shop/docs/platform-configuration/modules/warehousing): Inventory, stock management, and token handling
- [Worker Module](https://docs.unchained.shop/docs/platform-configuration/modules/worker): Background job processing and security configuration
- [Plugin Presets](https://docs.unchained.shop/docs/platform-configuration/plugin-presets): Pre-configured plugin bundles for quick setup
- [Post Delivery](https://docs.unchained.shop/docs/plugins/delivery/delivery-post): Standard postal delivery adapter
- [Send Message Delivery](https://docs.unchained.shop/docs/plugins/delivery/delivery-send-message): Digital delivery via messaging adapter
- [Stores Delivery](https://docs.unchained.shop/docs/plugins/delivery/delivery-stores): Store pickup delivery adapter
- [Delivery Plugins](https://docs.unchained.shop/docs/plugins/delivery): Delivery provider plugins for Unchained Engine
- [Licensed Enrollments](https://docs.unchained.shop/docs/plugins/enrollments/enrollment-licensed): Period-based subscription adapter for licensed products
- [Enrollment Plugins](https://docs.unchained.shop/docs/plugins/enrollments): Subscription and enrollment plugins for Unchained Engine
- [AWS EventBridge](https://docs.unchained.shop/docs/plugins/events/events-eventbridge): Enterprise event system using AWS EventBridge
- [Node.js Event Emitter](https://docs.unchained.shop/docs/plugins/events/events-node): In-memory event system using Node.js EventEmitter
- [Redis Events](https://docs.unchained.shop/docs/plugins/events/events-redis): Distributed event system using Redis pub/sub
- [Event Plugins](https://docs.unchained.shop/docs/plugins/events): Event system plugins for Unchained Engine
- [GridFS File Storage](https://docs.unchained.shop/docs/plugins/files/file-gridfs): MongoDB GridFS file storage for simple deployments
- [MinIO/S3 File Storage](https://docs.unchained.shop/docs/plugins/files/file-minio): S3-compatible file storage with MinIO or Amazon S3
- [File Storage Plugins](https://docs.unchained.shop/docs/plugins/files): File storage plugins for Unchained Engine
- [Local Search Filter](https://docs.unchained.shop/docs/plugins/filters/filter-local-search): MongoDB full-text search filter adapter
- [Strict Equal Filter](https://docs.unchained.shop/docs/plugins/filters/filter-strict-equal): Exact value matching filter adapter
- [Filter Plugins](https://docs.unchained.shop/docs/plugins/filters): Search and filtering plugins for Unchained Engine
- [Plugins](https://docs.unchained.shop/docs/plugins): Available Unchained Engine plugins
- [Apple In-App Purchase](https://docs.unchained.shop/docs/plugins/payment/apple-iap): Integrate Apple In-App Purchase as a payment provider for iOS app purchases in Unchained Engine.
- [Braintree](https://docs.unchained.shop/docs/plugins/payment/braintree): PayPal-owned payment processor for cards and digital wallets
- [Cryptopay](https://docs.unchained.shop/docs/plugins/payment/cryptopay): Self-hosted cryptocurrency payments (BTC, ETH, ERC20)
- [Datatrans](https://docs.unchained.shop/docs/plugins/payment/datatrans): Swiss payment service provider with multiple payment methods
- [Payment Plugins](https://docs.unchained.shop/docs/plugins/payment): Payment provider plugins for Unchained Engine
- [Invoice Prepaid Payment](https://docs.unchained.shop/docs/plugins/payment/invoice-prepaid): Prepayment invoice method requiring payment confirmation before fulfillment
- [Invoice Payment](https://docs.unchained.shop/docs/plugins/payment/invoice): Pay-per-invoice payment method for B2B and established customers
- [Payrexx](https://docs.unchained.shop/docs/plugins/payment/payrexx): Swiss payment provider supporting TWINT, PostFinance, and more
- [PostFinance Checkout](https://docs.unchained.shop/docs/plugins/payment/postfinance-checkout): Swiss PostFinance payment service integration
- [Saferpay](https://docs.unchained.shop/docs/plugins/payment/saferpay): Worldline Saferpay payment integration
- [Stripe](https://docs.unchained.shop/docs/plugins/payment/stripe): Payment processing with Stripe payment intents and saved payment methods
- [Pricing Plugins](https://docs.unchained.shop/docs/plugins/pricing): Pricing calculation plugins for Unchained Engine
- [Free Delivery Pricing](https://docs.unchained.shop/docs/plugins/pricing/pricing-delivery-free): Zero-cost delivery pricing adapter
- [Delivery Swiss Tax](https://docs.unchained.shop/docs/plugins/pricing/pricing-delivery-swiss-tax): Apply Swiss VAT to delivery fees
- [Discount 100 Off](https://docs.unchained.shop/docs/plugins/pricing/pricing-discount-100-off): Example fixed-amount coupon code discount
- [Discount Half Price Manual](https://docs.unchained.shop/docs/plugins/pricing/pricing-discount-half-price-manual): Coupon code for 50% discount on products
- [Discount Half Price](https://docs.unchained.shop/docs/plugins/pricing/pricing-discount-half-price): Automatic 50% discount for tagged users
- [Order Delivery Pricing](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-delivery): Add delivery fees to order total
- [Order Discount](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-discount): Apply discounts to total order value
- [Order Items Discount](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-items-discount): Apply discounts to order item totals only
- [Order Items Pricing](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-items): Sum product prices into order total
- [Order Payment Pricing](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-payment): Add payment fees to order total
- [Order Price Rounding](https://docs.unchained.shop/docs/plugins/pricing/pricing-order-round): Round order totals to configurable precision
- [Free Payment Pricing](https://docs.unchained.shop/docs/plugins/pricing/pricing-payment-free): Zero-cost payment pricing adapter
- [Product Catalog Price Options](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-catalog-price-options): Add prices for configurable product options
- [Product Catalog Price](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-catalog-price): Base product pricing from catalog prices
- [Product Discount](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-discount): Apply discounts to product prices
- [Product Rate Conversion](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-rate-conversion): Currency conversion for product prices
- [Product Price Rounding](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-round): Round product prices to configurable precision
- [Product Swiss Tax](https://docs.unchained.shop/docs/plugins/pricing/pricing-product-swiss-tax): Apply Swiss VAT to product prices
- [Quotation Plugins](https://docs.unchained.shop/docs/plugins/quotations): Quotation/offering plugins for Unchained Engine
- [Manual Quotations](https://docs.unchained.shop/docs/plugins/quotations/quotation-manual): Simple manual quotation adapter with configurable expiry
- [Warehousing Plugins](https://docs.unchained.shop/docs/plugins/warehousing): Warehousing and inventory plugins for Unchained Engine
- [ETH Minter](https://docs.unchained.shop/docs/plugins/warehousing/warehousing-eth-minter): NFT tokenization adapter for Web3 products
- [Store Warehousing](https://docs.unchained.shop/docs/plugins/warehousing/warehousing-store): Physical inventory management adapter
- [Worker Plugins](https://docs.unchained.shop/docs/plugins/workers): Background worker plugins for Unchained Engine
- [Push Notification Worker](https://docs.unchained.shop/docs/plugins/workers/push-notification): W3C compliant web push notifications
- [Twilio SMS Worker](https://docs.unchained.shop/docs/plugins/workers/twilio): Send SMS messages through Twilio
- [BudgetSMS Worker](https://docs.unchained.shop/docs/plugins/workers/worker-budgetsms): Send SMS messages through BudgetSMS
- [Bulk Import Worker](https://docs.unchained.shop/docs/plugins/workers/worker-bulk-import): Process large data imports from JSON streams
- [BulkGate SMS Worker](https://docs.unchained.shop/docs/plugins/workers/worker-bulkgate): Send SMS messages through BulkGate
- [Email Worker](https://docs.unchained.shop/docs/plugins/workers/worker-email): Email notification worker using Nodemailer
- [Enrollment Order Generator Worker](https://docs.unchained.shop/docs/plugins/workers/worker-enrollment-order-generator): Automatically generate orders from active enrollments
- [Error Notifications Worker](https://docs.unchained.shop/docs/plugins/workers/worker-error-notifications): Send daily reports about permanently failed work items
- [Export Token Worker](https://docs.unchained.shop/docs/plugins/workers/worker-export-token): External worker for NFT/token minting and export processes
- [External Worker](https://docs.unchained.shop/docs/plugins/workers/worker-external): Placeholder for external workers that interact via GraphQL
- [Heartbeat Worker](https://docs.unchained.shop/docs/plugins/workers/worker-heartbeat): Test worker to verify the worker system is functioning
- [HTTP Request Worker](https://docs.unchained.shop/docs/plugins/workers/worker-http-request): Process outbound HTTP requests and webhooks
- [Message Worker](https://docs.unchained.shop/docs/plugins/workers/worker-message): Route messages through templates to concrete delivery workers
- [Token Ownership Workers](https://docs.unchained.shop/docs/plugins/workers/worker-token-ownership): Workers for updating and refreshing NFT/token ownership
- [Coinbase Exchange Rate Worker](https://docs.unchained.shop/docs/plugins/workers/worker-update-coinbase-rates): Automatically update cryptocurrency and fiat exchange rates from Coinbase
- [ECB Exchange Rate Worker](https://docs.unchained.shop/docs/plugins/workers/worker-update-ecb-rates): Automatically update currency exchange rates from European Central Bank
- [Zombie Killer Worker](https://docs.unchained.shop/docs/plugins/workers/worker-zombie-killer): Clean up orphaned database records and files
- [Create Your First Order](https://docs.unchained.shop/docs/quick-start/first-order): Walk through the checkout flow to create your first order using the storefront and Admin UI.
- [Create Your First Product](https://docs.unchained.shop/docs/quick-start/first-product): Use the Admin UI to create, configure, and publish your first product in Unchained Engine.
- [Quick Start](https://docs.unchained.shop/docs/quick-start): Get started with Unchained Engine by setting up your environment, running locally or on Railway, and creating your first product and order.
- [Start your first Unchained Project](https://docs.unchained.shop/docs/quick-start/run-local): Create a new Unchained Engine project from the template, configure it, and run it locally with hot-reload.
- [Start your first Unchained Project on Railway](https://docs.unchained.shop/docs/quick-start/run-railway): Deploy an Unchained Engine project to Railway with automated CI pipelines and managed MongoDB.
- [Development Environment Setup](https://docs.unchained.shop/docs/quick-start/setup-environment): Install Node.js, MongoDB, and other prerequisites needed to develop with Unchained Engine.
- [FAQ](https://docs.unchained.shop/docs/troubleshooting/faq): Frequently asked questions about Unchained Engine
- [Troubleshooting](https://docs.unchained.shop/docs/troubleshooting): Common issues and solutions for Unchained Engine