Unchained Engine

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.

View Documentation

Quickstart

Prerequisites

• Node.js >=22 (see .nvmrc)
• MongoDB (or use MongoDB Memory Server for development)

Create a New Project

npm init @unchainedshop

Then navigate to http://localhost:4000/ to view the welcome screen. Login with:

• User: admin@unchained.local
• Password: password

Run Local AI for Copilot

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 2048

Package Architecture

Unchained 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)

Packages

Platform & API

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

Core Domain Modules

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

Infrastructure

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

Extensions

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

Admin UI

Package	Description
admin-ui	Next.js admin interface for managing the e-commerce platform

Examples

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

Plugin Architecture

Unchained uses a Director/Adapter pattern for extensibility. Directors manage collections of adapters that implement specific behaviors.

Available Directors

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.

Available Plugins

The @unchainedshop/plugins package includes:

Payment

• Stripe, PayPal, Braintree, Datatrans, Saferpay
• Payrexx, Cryptopay, Apple IAP
• Invoice (standard and prepaid)

Delivery

• Post (manual shipping), Store pickup, Digital delivery

Pricing

• Product catalog pricing, Currency conversion, Tax calculation (Swiss VAT)
• Order-level and product-level discounts, Price rounding

File Storage

• MongoDB GridFS, MinIO/S3-compatible storage

Workers

• Email (Nodemailer), SMS (Twilio, Bulkgate), Push notifications
• Currency rate updates (ECB, Coinbase), Bulk import

Events

• Node.js EventEmitter, Redis pub/sub, AWS EventBridge

Development

Commands

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

Testing

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

Project Structure

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

Migration Guide

See MIGRATION.md for upgrade instructions between major versions.

Claude Code Integration

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.

Security & Compliance

Unchained Engine is designed for deployment in security-sensitive environments including banking, government, and enterprise contexts.

Compliance

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

Cryptographic Standards

• 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

FIPS 140-3 Mode

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.js

See SECURITY.md for complete security documentation, compliance details, and deployment recommendations.

Resources

• Security Documentation
• Changelog
• Benchmarks

Contributing

Please see our Contribution Guidelines.

Code of Conduct

See our Contributor Covenant Code of Conduct.

License

EUPL-1.2