# Unchained Engine

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/unchained?referralCode=ZXvOAF)

Licensed under the EUPL 1.2

[![Static Badge](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/unchainedshop/unchained/issues)
[![Discord](https://img.shields.io/discord/1465319331457007668?label=Discord&logo=discord&color=5865F2)](https://discord.gg/WGdYTqtw72)

[![Bundle Size](https://pkg-size.dev/badge/bundle/1604171)](https://pkg-size.dev/@unchainedshop/platform)
[![CLA assistant](https://cla-assistant.io/readme/badge/unchainedshop/unchained)](https://cla-assistant.io/unchainedshop/unchained)

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](https://docs.unchained.shop)**

## Quickstart

### Prerequisites

- Node.js >=26 (see [.nvmrc](.nvmrc) for the development version)
- MongoDB 4.4+ (or use MongoDB Memory Server for development)

### Create a New Project

```bash
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](docs/docs/platform-configuration/enable-copilot.md).

```bash
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](packages/platform/README.md) | Complete engine bundle - main entry point combining api, core, plugins, and infrastructure |
| [@unchainedshop/api](packages/api/README.md) | GraphQL API with Express/Fastify adapters and MCP server for AI integrations |
| [@unchainedshop/core](packages/core/README.md) | Core orchestration with business services, directors, and bulk import |

### Core Domain Modules

Business logic modules for e-commerce functionality:

| Package | Description |
|---------|-------------|
| [@unchainedshop/core-products](packages/core-products/README.md) | Product management with pricing, media, reviews, and variations |
| [@unchainedshop/core-orders](packages/core-orders/README.md) | Order lifecycle including positions, payments, deliveries, and discounts |
| [@unchainedshop/core-users](packages/core-users/README.md) | User accounts, authentication, profiles, and WebAuthn support |
| [@unchainedshop/core-payment](packages/core-payment/README.md) | Payment provider management and credentials |
| [@unchainedshop/core-delivery](packages/core-delivery/README.md) | Delivery provider management and shipping methods |
| [@unchainedshop/core-assortments](packages/core-assortments/README.md) | Category management with hierarchical structures |
| [@unchainedshop/core-filters](packages/core-filters/README.md) | Product filtering and faceted search |
| [@unchainedshop/core-warehousing](packages/core-warehousing/README.md) | Inventory, stock management, and token surrogates |
| [@unchainedshop/core-enrollments](packages/core-enrollments/README.md) | Subscription/enrollment management |
| [@unchainedshop/core-quotations](packages/core-quotations/README.md) | Quote requests and proposal workflows |
| [@unchainedshop/core-bookmarks](packages/core-bookmarks/README.md) | User bookmark/wishlist functionality |
| [@unchainedshop/core-files](packages/core-files/README.md) | File metadata storage and URL management |
| [@unchainedshop/core-events](packages/core-events/README.md) | Event history persistence and analytics |
| [@unchainedshop/core-worker](packages/core-worker/README.md) | Background job queue and processing |
| [@unchainedshop/core-countries](packages/core-countries/README.md) | Country management with ISO codes |
| [@unchainedshop/core-currencies](packages/core-currencies/README.md) | Currency management and blockchain support |
| [@unchainedshop/core-languages](packages/core-languages/README.md) | Language management for i18n |

### Infrastructure

Foundational utilities used across all layers:

| Package | Description |
|---------|-------------|
| [@unchainedshop/mongodb](packages/mongodb/README.md) | MongoDB database abstraction with utilities and DocumentDB compatibility |
| [@unchainedshop/events](packages/events/README.md) | Event emitter abstraction with Node.js, Redis, and EventBridge adapters |
| [@unchainedshop/logger](packages/logger/README.md) | High-performance logging with JSON/human-readable formats |
| [@unchainedshop/utils](packages/utils/README.md) | Common utilities, locale helpers, and cryptographic helpers |
| [@unchainedshop/roles](packages/roles/README.md) | Role-based access control (RBAC) system |
| [@unchainedshop/shared](packages/shared/README.md) | Shared TypeScript configuration for workspace packages |

### Extensions

| Package | Description |
|---------|-------------|
| [@unchainedshop/plugins](packages/plugins/README.md) | Official plugin collection for payment, delivery, pricing, and more |
| [@unchainedshop/ticketing](packages/ticketing/README.md) | Event ticketing: ticket issuer, gate control, cancellations, and routes for your PDF and wallet pass renderers |

### Admin UI

| Package | Description |
|---------|-------------|
| [admin-ui](admin-ui/README.md) | Next.js admin interface for managing the e-commerce platform |

### Examples

| Example | Description |
|---------|-------------|
| [Kitchensink (Fastify)](examples/kitchensink/README.md) | Full-featured example with Fastify, all plugins, Admin UI extensions, and AI integration |
| [Kitchensink (Express)](examples/kitchensink-express/README.md) | Full-featured example with Express, MCP server, and AI integration |
| [Ticketing](examples/ticketing/README.md) | Event ticketing with the ticket issuer, gate staff and sale validation |
| [Minimal](examples/minimal/README.md) | Minimal setup example |
| [OIDC](examples/oidc/README.md) | 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](packages/core/README.md) for detailed documentation on creating custom adapters.

## Available Plugins

The [@unchainedshop/plugins](packages/plugins/README.md) 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

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

```bash
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](MIGRATION.md) for upgrade instructions between major versions.

## Claude Code Integration

The [upgrade skill](docs/static/skills/upgrade-unchained/SKILL.md) 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](SECURITY.md#fips-140-3-compatibility) 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](https://escape.tech/graphql-armor/):

   ```ts
   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](SECURITY.md) for complete security documentation, compliance details, and deployment recommendations.

## Resources

- [Security Documentation](SECURITY.md)
- [Changelog](CHANGELOG.md)

## Contributing

Please see our [Contribution Guidelines](CONTRIBUTING.md).

## Code of Conduct

See our [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

## License

EUPL-1.2