Headless Commerce with React Router: Modern Architecture

// Type-safe Shopify Storefront API integration
import { createStorefrontApiClient } from '@shopify/storefront-api-client';

const storefront = createStorefrontApiClient({
storeDomain: 'https://your-shop.myshopify.com',
apiVersion: '2024-01',
publicAccessToken: process.env.SHOPIFY_STOREFRONT_TOKEN,
});

// React Router loader with headless data fetching
export async function loader({ params }: LoaderArgs) {
const { handle } = params;

const query = `
  query GetProduct($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      images(first: 10) {
        edges {
          node {
            url
            altText
            width
            height
          }
        }
      }
      variants(first: 250) {
        edges {
          node {
            id
            title
            price {
              amount
              currencyCode
            }
            availableForSale
          }
        }
      }
    }
  }
`;

const response = await storefront.request(query, { variables: { handle } });

if (!response.data?.product) {
  throw new Response('Product not found', { status: 404 });
}

return { product: response.data.product };
}

// Complex headless commerce queries
const PRODUCT_COLLECTION_QUERY = `
query ProductCollection(
  $handle: String!
  $first: Int!
  $filters: [ProductFilter!]
  $sortKey: ProductCollectionSortKeys!
) {
  collection(handle: $handle) {
    id
    title
    description
    products(
      first: $first
      filters: $filters
      sortKey: $sortKey
    ) {
      edges {
        node {
          ...ProductFragment
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      filters {
        id
        label
        type
        values {
          id
          label
          count
          input
        }
      }
    }
  }
}

fragment ProductFragment on Product {
  id
  handle
  title
  description
  priceRange {
    minVariantPrice {
      amount
      currencyCode
    }
    maxVariantPrice {
      amount
      currencyCode  
    }
  }
  compareAtPriceRange {
    minVariantPrice {
      amount
      currencyCode
    }
  }
  images(first: 5) {
    edges {
      node {
        url
        altText
        width
        height
      }
    }
  }
}
`;

// Type-safe data fetching with caching
export async function getProductCollection({
handle,
first = 24,
filters = [],
sortKey = 'BEST_SELLING'
}: CollectionQueryParams): Promise<Collection> {
const response = await storefront.request(PRODUCT_COLLECTION_QUERY, {
  variables: { handle, first, filters, sortKey }
});

return response.data.collection;
}

// Shared commerce logic across channels
interface CommerceChannel {
id: string;
name: string;
platform: 'web' | 'mobile' | 'pos' | 'iot' | 'social';
capabilities: ChannelCapability[];
}

// Universal cart management
export class UniversalCart {
private cartId: string;
private channel: CommerceChannel;

async addLineItem(
  variantId: string,
  quantity: number,
  channel: CommerceChannel
): Promise<Cart> {
  // Channel-specific optimizations
  const optimizedRequest = this.optimizeForChannel(
    { variantId, quantity },
    channel
  );
  
  // Universal Shopify Cart API
  const response = await fetch('/api/cart/add', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...optimizedRequest,
      cartId: this.cartId,
      channel: channel.id,
    }),
  });
  
  return response.json();
}

// Real-time synchronization across channels
async syncAcrossChannels(): Promise<void> {
  const channels = await this.getActiveChannels();
  
  await Promise.all(
    channels.map(channel => 
      this.syncCartToChannel(this.cartId, channel)
    )
  );
}
}

// WebSocket-based real-time inventory
import { useEffect, useState } from 'react';

interface InventoryUpdate {
variantId: string;
availableQuantity: number;
timestamp: string;
}

export function useRealTimeInventory(variantIds: string[]) {
const [inventory, setInventory] = useState<Map<string, number>>(new Map());
const [socket, setSocket] = useState<WebSocket | null>(null);

useEffect(() => {
  const ws = new WebSocket('wss://inventory.your-app.com/subscribe');
  
  ws.onopen = () => {
    // Subscribe to variant inventory updates
    ws.send(JSON.stringify({
      type: 'SUBSCRIBE',
      variantIds,
    }));
  };
  
  ws.onmessage = (event) => {
    const update: InventoryUpdate = JSON.parse(event.data);
    
    setInventory(prev => new Map(prev).set(
      update.variantId,
      update.availableQuantity
    ));
    
    // Trigger UI updates for low stock warnings
    if (update.availableQuantity < 5) {
      showLowStockNotification(update.variantId);
    }
  };
  
  setSocket(ws);
  
  return () => {
    ws.close();
  };
}, [variantIds]);

return { inventory, isConnected: socket?.readyState === WebSocket.OPEN };
}

// Component usage
export function ProductPage() {
const { product } = useLoaderData<typeof loader>();
const variantIds = product.variants.edges.map(edge => edge.node.id);
const { inventory } = useRealTimeInventory(variantIds);

return (
  <div>
    {product.variants.edges.map(({ node: variant }) => (
      <VariantOption
        key={variant.id}
        variant={variant}
        availableQuantity={inventory.get(variant.id)}
        showLowStock={inventory.get(variant.id) < 5}
      />
    ))}
  </div>
);
}

// Headless personalization service
interface UserBehavior {
userId: string;
sessionId: string;
viewedProducts: string[];
cartActions: CartAction[];
purchaseHistory: Purchase[];
preferences: UserPreferences;
}

export class PersonalizationEngine {
async getPersonalizedRecommendations(
  userId: string,
  context: CommerceContext
): Promise<PersonalizedContent> {
  // Fetch user behavior data
  const behavior = await this.getUserBehavior(userId);
  
  // AI-powered recommendation generation
  const recommendations = await fetch('/api/ai/recommendations', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId,
      behavior,
      context,
      algorithm: 'collaborative-filtering-v2',
    }),
  }).then(res => res.json());
  
  // Real-time A/B testing
  const optimizedContent = await this.applyABTesting(
    recommendations,
    userId
  );
  
  return {
    products: optimizedContent.products,
    collections: optimizedContent.collections,
    content: optimizedContent.content,
    confidence: optimizedContent.confidence,
  };
}
}

// Centralized API gateway for headless services
export class CommerceAPIGateway {
private services = {
  shopify: new ShopifyStorefrontClient(),
  inventory: new InventoryService(),
  reviews: new ReviewsService(), 
  recommendations: new RecommendationEngine(),
  analytics: new AnalyticsService(),
};

async aggregateProductData(productId: string): Promise<EnrichedProduct> {
  // Parallel API calls for optimal performance
  const [product, inventory, reviews, recommendations] = await Promise.all([
    this.services.shopify.getProduct(productId),
    this.services.inventory.getAvailability(productId),
    this.services.reviews.getProductReviews(productId),
    this.services.recommendations.getRelatedProducts(productId),
  ]);
  
  // Merge data from multiple services
  return {
    ...product,
    realTimeInventory: inventory,
    customerReviews: reviews,
    relatedProducts: recommendations,
    aggregatedAt: new Date().toISOString(),
  };
}
}