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 >=26 (see .nvmrc for the development version)
• MongoDB 4.4+ (or use MongoDB Memory Server for development)

Create a New Project

npm init @unchainedshop

Then navigate to http://localhost:4010/ to open the Admin UI and set up your administrator account on first run.

Run Local AI for Copilot

Hardware requirements depend on the model, quantization, and context size. For an OpenAI-compatible local server, see the Copilot configuration guide.

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 Node.js, Redis, and EventBridge adapters
@unchainedshop/logger	High-performance logging with JSON/human-readable formats
@unchainedshop/utils	Common utilities, locale helpers, and cryptographic helpers
@unchainedshop/roles	Role-based access control (RBAC) system
@unchainedshop/shared	Shared TypeScript configuration for workspace packages

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, Admin UI extensions, 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, Datatrans, 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, Datatrans, Saferpay, PostFinance Checkout
• Payrexx, Cryptopay, Apple IAP
• Invoice (standard and prepaid)

Delivery

• Post (manual shipping), Store pickup, Message-based delivery

Pricing

• Product catalog pricing, Currency conversion, Tax calculation (Swiss, EU, UK, US)
• Order-level and product-level discounts

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

The upgrade skill guides agents through the 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	Deployment-dependent	Payment integrations use provider tokens; assess the complete payment flow
ISO 27001 / FINMA / NIS2	Technical controls	Access control and audit events can support organizational controls
FIPS 140-3	Deployment-dependent	Validate the runtime and each enabled authentication/payment integration

Cryptographic Standards

• Password Hashing: PBKDF2-SHA512 with 300,000 iterations
• Token Security: SHA-256 hashing, cryptographically random generation
• Login Tokens: HS256-signed JWTs with a one-hour default lifetime
• Payment Signatures: HMAC-SHA-256/512

FIPS 140-3 Mode

For deployments requiring FIPS, verify the runtime and all enabled integrations. See FIPS configuration for the runtime requirements and verification steps.

API Hardening (Denial-of-Service Protection)

The GraphQL API does not impose query-complexity, depth, alias-count, or rate limits by default. Unchained is a headless engine embedded in your own server process, so where and how these edge protections are enforced is a deployment decision that belongs to the integrator — appropriate thresholds depend on your schema extensions, traffic profile, and infrastructure (CDN, WAF, API gateway, reverse proxy).

Anonymous access is enabled by default for read-only storefront queries (e.g. assortments, products, filters, languages, currencies, countries, search). Because GraphQL lets a single request batch many aliased fields, an unbounded query can fan out into many database operations. Bounding this is the operator's responsibility.

Recommended layers:

1. Query validation (in-process). GraphQL Yoga plugins and validation rules are forwarded straight through startPlatform / startAPIServer to the underlying Yoga server. For example, using 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 }),
     ],
   });

2. Rate limiting & request-size limits (at the edge). Enforce per-IP / per-token rate limits and body-size caps at your reverse proxy, API gateway, or WAF (e.g. nginx limit_req, Cloudflare, AWS WAF). Keep anonymous traffic on a tighter budget than authenticated traffic.

3. Pagination caps. If you expose custom list resolvers, clamp limit / pagination server-side.

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

Resources

• Security Documentation
• Changelog

Contributing

Please see our Contribution Guidelines.

Code of Conduct

See our Contributor Covenant Code of Conduct.

License

EUPL-1.2