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

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

Core Domain Modules

Business logic modules for e-commerce functionality:

Infrastructure

Foundational utilities used across all layers:

Extensions

Admin UI

Examples

Plugin Architecture

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

Available Directors

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

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

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

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
• Benchmarks

Contributing

Please see our Contribution Guidelines.

Code of Conduct

See our Contributor Covenant Code of Conduct.

License

EUPL-1.2