composable-commerce

What this skill does

# Composable Commerce

## Overview

Composable commerce is an architectural approach based on MACH principles — Microservices, API-first, Cloud-native, Headless — where each commerce capability (cart, catalog, search, CMS, checkout, loyalty) is provided by a best-of-breed service rather than a monolithic platform. Services communicate via APIs and events, enabling teams to replace or upgrade individual capabilities without touching the rest of the system. This skill covers MACH architecture patterns, service integration, event-driven coordination, and the operational considerations of running a composable stack in production.

## When to Use This Skill

- When a monolithic platform (Magento, Salesforce CC) can no longer scale with your team or traffic patterns
- When different domains (catalog, checkout, loyalty) have divergent release cadences and ownership
- When you need to mix best-of-breed vendors — e.g., Algolia for search, Contentful for CMS, commercetools for commerce
- When entering new markets requiring different fulfillment, pricing, or tax providers per region
- When building a platform that must support multiple storefronts (web, mobile, in-store, B2B portal) from a single backend

## Prerequisites & Platform Notes

**This skill is written for custom/headless storefronts** (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

**Shopify**: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services.
**WooCommerce**: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress.
**Magento**: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

**You'll need**:
- Node.js 18+ (or adapt to your backend language)
- PostgreSQL (or your preferred relational database)
- A search service (Algolia, Elasticsearch, or Typesense)
- Stripe account and API keys
- An email sending service (SendGrid, AWS SES, or Postmark)

## Core Instructions

1. **Design service boundaries around commerce capabilities**

   A typical composable commerce stack separates capabilities into discrete services:

   | Capability | Example Services |
   |-----------|-----------------|
   | Product Catalog | commercetools, Akeneo PIM, Salsify |
   | Search & Discovery | Algolia, Elasticsearch, Constructor.io |
   | CMS / Content | Contentful, Sanity, Storyblok |
   | Cart & Checkout | commercetools, Elastic Path, Medusa |
   | Payments | Stripe, Adyen, Braintree |
   | Tax | Avalara, TaxJar |
   | Shipping & Fulfillment | EasyPost, ShipBob, custom OMS |
   | Customer Identity | Auth0, Okta, Cognito |
   | Loyalty & Promotions | Talon.One, Voucherify |
   | Email / Notifications | SendGrid, Customer.io |

   Define bounded contexts: each service owns its data and exposes it only via APIs. Never share databases between services.

2. **Implement an API composition layer (BFF)**

   A Backend-for-Frontend (BFF) aggregates multiple upstream APIs into a single request, tailored to what the frontend needs:

   ```typescript
   // bff/src/routes/product-page.ts
   import {getProduct} from '../services/catalog';
   import {getSearchReviews} from '../services/reviews';
   import {getRecommendations} from '../services/recommendations';
   import {getInventory} from '../services/inventory';

   export async function productPageData(productId: string, customerId?: string) {
     // Parallel fetch from independent services
     const [product, inventory, recommendations] = await Promise.all([
       getProduct(productId),
       getInventory(productId),
       getRecommendations(productId, customerId),
     ]);

     // Sequential: reviews needs product.sku
     const reviews = await getSearchReviews(product.sku);

     return {
       product,
       inventory,
       recommendations,
       reviews,
     };
   }
   ```

   Expose the BFF as a GraphQL API using schema stitching or federation:

   ```typescript
   import {buildHTTPExecutor} from '@graphql-tools/executor-http';
   import {stitchSchemas} from '@graphql-tools/stitch';

   const gatewaySchema = await stitchSchemas({
     subschemas: [
       { schema: await introspectSchema(catalogExecutor), executor: catalogExecutor },
       { schema: await introspectSchema(inventoryExecutor), executor: inventoryExecutor },
       { schema: await introspectSchema(reviewsExecutor), executor: reviewsExecutor },
     ],
   });
   ```

3. **Use event-driven architecture for cross-service coordination**

   Services should communicate asynchronously for workflows that span multiple capabilities (order placed → inventory reserved → fulfillment triggered → email sent):

   ```typescript
   // Order service publishes an event after checkout
   import {EventBridge} from '@aws-sdk/client-eventbridge';

   const eventBridge = new EventBridge({region: 'us-east-1'});

   async function publishOrderPlaced(order: Order) {
     await eventBridge.putEvents({
       Entries: [
         {
           Source: 'commerce.orders',
           DetailType: 'OrderPlaced',
           Detail: JSON.stringify({
             orderId: order.id,
             customerId: order.customerId,
             lineItems: order.lineItems,
             totalAmount: order.totalAmount,
             currency: order.currency,
           }),
           EventBusName: 'commerce-events',
         },
       ],
     });
   }

   // Inventory service subscribes and reserves stock
   // EventBridge rule routes OrderPlaced → Lambda → inventory-service
   export async function handler(event: EventBridgeEvent<'OrderPlaced', OrderPayload>) {
     const {orderId, lineItems} = event.detail;
     await reserveInventory(lineItems);
     await publishInventoryReserved(orderId);
   }
   ```

4. **Implement the Saga pattern for distributed transactions**

   When a multi-step workflow must be atomic across services, use orchestrated sagas with compensating transactions:

   ```typescript
   // Choreography-based saga for order fulfillment
   // Each service publishes events and reacts to others

   // Order Service
   on('CheckoutCompleted', async ({orderId, paymentIntentId}) => {
     await orders.create({orderId, status: 'pending_payment'});
     await publish('OrderCreated', {orderId, paymentIntentId});
   });

   // Payment Service
   on('OrderCreated', async ({orderId, paymentIntentId}) => {
     try {
       await capturePayment(paymentIntentId);
       await publish('PaymentCaptured', {orderId});
     } catch (err) {
       await publish('PaymentFailed', {orderId, reason: err.message});
     }
   });

   // Fulfillment Service
   on('PaymentCaptured', async ({orderId}) => {
     await fulfillment.schedule(orderId);
   });

   // Order Service — compensate on failure
   on('PaymentFailed', async ({orderId}) => {
     await orders.update(orderId, {status: 'payment_failed'});
     await releaseInventory(orderId);
     await notifyCustomer(orderId, 'payment_failed');
   });
   ```

5. **Manage API versioning and backward compatibility**

   In a composable stack, services evolve independently. Use additive versioning strategies:

   ```typescript
   // Use content negotiation or URL versioning
   // GET /api/v2/products/:id
   // Accept: application/vnd.commerce.product.v2+json

   // Apply the Tolerant Reader pattern — ignore unknown fields
   interface ProductV1 {
     id: string;
     name: string;
     price: number;
   }

   // V2 adds fields — existing consumers still work
   interface ProductV2 extends ProductV1 {
     categories?: string[];
     attributes?: Record<string, string>;
     brand?: string;
   }

   // Use feature flags to roll out breaking changes
   async function getProduct(id: string, apiVersion: '1' | '2' =