Licensed under the EUPL 1.2
Unchained Engine is a modular, API-first e-commerce platform built as a monorepo with npm workspaces. It provides a complete solution for building custom e-commerce applications with GraphQL APIs, extensible plugin architecture, and support for modern use cases like subscriptions, quotations, and tokenized products.
- Node.js >=22 (see .nvmrc)
- MongoDB (or use MongoDB Memory Server for development)
npm init @unchainedshopThen navigate to http://localhost:4000/ to view the welcome screen. Login with:
- User: [email protected]
- Password: password
A minimum of 24GB VRAM is needed for this.
llama-server -hf ggml-org/gpt-oss-20b-GGUF --ctx-size 0 --jinja -ub 2048 -b 2048Unchained Engine is organized in a hierarchical structure:
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)
| Package | Description |
|---|---|
| @unchainedshop/platform | Complete engine bundle - main entry point combining api, core, plugins, and infrastructure |
| @unchainedshop/api | GraphQL API with Express/Fastify adapters and MCP server for AI integrations |
| @unchainedshop/core | Core orchestration with business services, directors, and bulk import |
Business logic modules for e-commerce functionality:
| Package | Description |
|---|---|
| @unchainedshop/core-products | Product management with pricing, media, reviews, and variations |
| @unchainedshop/core-orders | Order lifecycle including positions, payments, deliveries, and discounts |
| @unchainedshop/core-users | User accounts, authentication, profiles, and WebAuthn support |
| @unchainedshop/core-payment | Payment provider management and credentials |
| @unchainedshop/core-delivery | Delivery provider management and shipping methods |
| @unchainedshop/core-assortments | Category management with hierarchical structures |
| @unchainedshop/core-filters | Product filtering and faceted search |
| @unchainedshop/core-warehousing | Inventory, stock management, and token surrogates |
| @unchainedshop/core-enrollments | Subscription/enrollment management |
| @unchainedshop/core-quotations | Quote requests and proposal workflows |
| @unchainedshop/core-bookmarks | User bookmark/wishlist functionality |
| @unchainedshop/core-files | File metadata storage and URL management |
| @unchainedshop/core-events | Event history persistence and analytics |
| @unchainedshop/core-worker | Background job queue and processing |
| @unchainedshop/core-countries | Country management with ISO codes |
| @unchainedshop/core-currencies | Currency management and blockchain support |
| @unchainedshop/core-languages | Language management for i18n |
Foundational utilities used across all layers:
| Package | Description |
|---|---|
| @unchainedshop/mongodb | MongoDB database abstraction with utilities and DocumentDB compatibility |
| @unchainedshop/events | Event emitter abstraction with pluggable adapters (Redis, Kafka, etc.) |
| @unchainedshop/logger | High-performance logging with JSON/human-readable formats |
| @unchainedshop/utils | Common utilities, locale helpers, and Director/Adapter base classes |
| @unchainedshop/roles | Role-based access control (RBAC) system |
| @unchainedshop/file-upload | File upload abstraction with pluggable storage backends |
| Package | Description |
|---|---|
| @unchainedshop/plugins | Official plugin collection for payment, delivery, pricing, and more |
| @unchainedshop/ticketing | Event ticketing with PDF generation and Apple/Google Wallet passes |
| Package | Description |
|---|---|
| admin-ui | Next.js admin interface for managing the e-commerce platform |
| Example | Description |
|---|---|
| Kitchensink (Fastify) | Full-featured example with Fastify, all plugins, ticketing, and AI integration |
| Kitchensink (Express) | Full-featured example with Express, MCP server, and AI integration |
| Ticketing | Event ticketing with PDF and wallet passes |
| Minimal | Minimal setup example |
| OIDC | OpenID Connect authentication example |
Unchained uses a Director/Adapter pattern for extensibility. Directors manage collections of adapters that implement specific behaviors.
| Director | Purpose | Example Adapters |
|---|---|---|
PaymentDirector |
Payment processing | Stripe, PayPal, Invoice |
DeliveryDirector |
Shipping/delivery | Post, Pickup, Digital |
WarehousingDirector |
Inventory management | Store, ETH Minter |
WorkerDirector |
Background jobs | Email, SMS, HTTP Request |
FilterDirector |
Product search | Strict Equal, Local Search |
ProductPricingDirector |
Product pricing | Catalog Price, Discounts |
OrderPricingDirector |
Order totals | Items, Delivery, Payment |
MessagingDirector |
Notifications | Email templates, SMS |
See the Core README for detailed documentation on creating custom adapters.
The @unchainedshop/plugins package includes:
- Stripe, PayPal, Braintree, Datatrans, Saferpay
- Payrexx, Cryptopay, Apple IAP
- Invoice (standard and prepaid)
- Post (manual shipping), Store pickup, Digital delivery
- Product catalog pricing, Currency conversion, Tax calculation (Swiss VAT)
- Order-level and product-level discounts, Price rounding
- MongoDB GridFS, MinIO/S3-compatible storage
- Email (Nodemailer), SMS (Twilio, Bulkgate), Push notifications
- Currency rate updates (ECB, Coinbase), Bulk import
- Node.js EventEmitter, Redis pub/sub, AWS EventBridge
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 codenpm 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 fileunchained/
├── 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
See MIGRATION.md for upgrade instructions between major versions.
Unchained provides a Claude Code skill to help with upgrades:
claude "skill install https://docs.unchained.shop/skills/upgrade-unchained/SKILL.md"This skill guides Claude through fetching the correct migration guide, changelog, and examples for your target version.
Unchained Engine is designed for deployment in security-sensitive environments including banking, government, and enterprise contexts.
| Standard | Status | Notes |
|---|---|---|
| PCI DSS SAQ-A | Eligible | Payment tokenization, no card data storage |
| ISO 27001 | Aligned | Comprehensive security controls |
| FIPS 140-3 | Supported | Deploy with FIPS-enabled Node.js |
| FINMA/NIS2 | Aligned | Banking and EU requirements |
- Password Hashing: PBKDF2-SHA512 with 300,000 iterations
- Token Security: SHA-256 hashing, cryptographically random generation
- Session Encryption: AES-256-GCM (optional)
- Payment Signatures: HMAC-SHA-256/512
For US federal government and regulated environments, run Unchained with FIPS-validated cryptography:
# Use Chainguard FIPS image
FROM cgr.dev/chainguard/node-fips:latest
WORKDIR /app
COPY . .
CMD ["node", "index.js"]Or enable FIPS mode manually:
node --enable-fips your-app.jsSee SECURITY.md for complete security documentation, compliance details, and deployment recommendations.
Please see our Contribution Guidelines.
See our Contributor Covenant Code of Conduct.
EUPL-1.2