Project - Headless Magento Storefront

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   React Storefront                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ Product  │  │   Cart   │  │ Checkout │          │
│  │ Listing  │  │  Module  │  │  Module  │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │              │              │                 │
│       └──────────────┼──────────────┘                 │
│                      │                               │
│              ┌───────┴───────┐                       │
│              │  Apollo Client │                       │
│              │  (GraphQL)    │                       │
│              └───────┬───────┘                       │
└──────────────────────┼───────────────────────────────┘
                       │
                ┌──────┴──────┐
                │   Magento   │
                │  GraphQL    │
                │  Endpoint   │
                └──────┬──────┘
                       │
                ┌──────┴──────┐
                │  Magento 2  │
                │  Backend    │
                └─────────────┘

Project Structure

magento-headless/
├── src/
│   ├── components/
│   │   ├── Product/
│   │   │   ├── ProductCard.tsx
│   │   │   ├── ProductList.tsx
│   │   │   └── ProductDetail.tsx
│   │   ├── Cart/
│   │   │   ├── CartDrawer.tsx
│   │   │   ├── CartItem.tsx
│   │   │   └── CartSummary.tsx
│   │   ├── Checkout/
│   │   │   ├── CheckoutFlow.tsx
│   │   │   ├── AddressForm.tsx
│   │   │   └── PaymentMethod.tsx
│   │   ├── Header/
│   │   │   ├── Navigation.tsx
│   │   │   └── MiniCart.tsx
│   │   └── common/
│   │       ├── Loading.tsx
│   │       └── ErrorBoundary.tsx
│   ├── graphql/
│   │   ├── queries/
│   │   │   ├── GET_PRODUCTS.ts
│   │   │   ├── GET_PRODUCT.ts
│   │   │   └── GET_CART.ts
│   │   ├── mutations/
│   │   │   ├── ADD_TO_CART.ts
│   │   │   ├── CREATE_CART.ts
│   │   │   └── PLACE_ORDER.ts
│   │   └── client.ts
│   ├── hooks/
│   │   ├── useCart.ts
│   │   ├── useAuth.ts
│   │   └── useProducts.ts
│   ├── pages/
│   │   ├── Home.tsx
│   │   ├── ProductList.tsx
│   │   ├── ProductDetail.tsx
│   │   ├── Cart.tsx
│   │   └── Checkout.tsx
│   ├── utils/
│   │   ├── auth.ts
│   │   ├── cart.ts
│   │   └── pushNotifications.ts
│   └── App.tsx
├── public/
│   ├── manifest.json
│   └── offline.html
├── package.json
└── tsconfig.json

The React frontend communicates exclusively via GraphQL to the Magento backend, enabling independent deployment and scaling.

Product Queries

// src/graphql/queries/GET_PRODUCTS.ts
import { gql } from '@apollo/client';

export const GET_PRODUCTS = gql`
    query GetProducts(
        $search: String
        $filter: ProductAttributeFilterInput
        $sort: ProductAttributeSortInput
        $pageSize: Int
        $currentPage: Int
    ) {
        products(
            search: $search
            filter: $filter
            sort: $sort
            pageSize: $pageSize
            currentPage: $currentPage
        ) {
            total_count
            items {
                id
                name
                sku
                url_key
                price_range {
                    minimum_price {
                        regular_price { value currency }
                        final_price { value currency }
                        discount { amount_off percent_off }
                    }
                }
                image {
                    url
                    label
                }
                stock_status
                ... on ConfigurableProduct {
                    variants {
                        product {
                            sku
                            name
                            stock_status
                            price_range {
                                minimum_price {
                                    final_price { value currency }
                                }
                            }
                        }
                        attributes {
                            label
                            code
                        }
                    }
                }
            }
            page_info {
                current_page
                page_size
                total_pages
            }
        }
    }
`;

export const GET_PRODUCT = gql`
    query GetProduct($urlKey: String!) {
        products(filter: { url_key: { eq: $urlKey } }) {
            items {
                id
                name
                sku
                url_key
                description { html }
                short_description { html }
                price_range {
                    minimum_price {
                        regular_price { value currency }
                        final_price { value currency }
                    }
                }
                media_gallery {
                    url
                    label
                    position
                }
                stock_status
                ... on ConfigurableProduct {
                    configurable_options {
                        attribute_code
                        label
                        values { label value_index }
                    }
                }
            }
        }
    }
`;

Cart Mutations

// src/graphql/mutations/ADD_TO_CART.ts
import { gql } from '@apollo/client';

export const CREATE_CART = gql`
    mutation CreateCart {
        createEmptyCart
    }
`;

export const ADD_TO_CART = gql`
    mutation AddToCart($cartId: String!, $cartItems: [CartInput!]!) {
        addProductsToCart(cartId: $cartId, cartItems: $cartItems) {
            cart {
                items {
                    uid
                    product { name sku }
                    quantity
                    prices { row_total { value currency } }
                }
                prices {
                    grand_total { value currency }
                    subtotal_excluding_tax { value currency }
                }
            }
        }
    }
`;

export const PLACE_ORDER = gql`
    mutation PlaceOrder($cartId: String!) {
        placeOrder(input: { cart_id: $cartId }) {
            order {
                order_number
                order_id
            }
        }
    }
`;

GraphQL provides exactly the data needed per request, reducing over-fetching compared to REST endpoints.

Product Card Component

// src/components/Product/ProductCard.tsx
import React from 'react';
import { Link } from 'react-router-dom';
import { useCart } from '../../hooks/useCart';

interface Product {
    id: string;
    name: string;
    sku: string;
    url_key: string;
    price_range: {
        minimum_price: {
            final_price: { value: number; currency: string };
            discount?: { amount_off: number; percent_off: number };
        };
    };
    image: { url: string; label: string };
    stock_status: string;
}

interface ProductCardProps {
    product: Product;
}

export const ProductCard: React.FC<ProductCardProps> = ({ product }) => {
    const { addToCart, loading } = useCart();
    const price = product.price_range.minimum_price;

    const handleAddToCart = async () => {
        await addToCart(product.sku, 1);
    };

    return (
        <div className="product-card">
            <Link to={`/product/${product.url_key}`}>
                <div className="product-image">
                    <img src={product.image.url} alt={product.image.label} />
                    {price.discount && (
                        <span className="discount-badge">
                            -{price.discount.percent_off}%
                        </span>
                    )}
                </div>
                <div className="product-info">
                    <h3 className="product-name">{product.name}</h3>
                    <div className="product-price">
                        <span className="final-price">
                            {price.final_price.currency} {price.final_price.value.toFixed(2)}
                        </span>
                        {price.discount && (
                            <span className="regular-price">
                                {price.regular_price?.value.toFixed(2)}
                            </span>
                        )}
                    </div>
                </div>
            </Link>
            <button
                onClick={handleAddToCart}
                disabled={loading || product.stock_status !== 'IN_STOCK'}
                className="add-to-cart-btn"
            >
                {product.stock_status === 'IN_STOCK' ? 'Add to Cart' : 'Out of Stock'}
            </button>
        </div>
    );
};

useCart Hook

// src/hooks/useCart.ts
import { useState, useEffect } from 'react';
import { useMutation, useQuery } from '@apollo/client';
import { CREATE_CART, ADD_TO_CART } from '../graphql/mutations/ADD_TO_CART';
import { GET_CART } from '../graphql/queries/GET_CART';

export const useCart = () => {
    const [cartId, setCartId] = useState<string | null>(
        () => localStorage.getItem('cart_id')
    );

    const [createCart] = useMutation(CREATE_CART);
    const [addProductsMutation, { loading }] = useMutation(ADD_TO_CART);

    const { data: cartData, refetch } = useQuery(GET_CART, {
        variables: { cartId },
        skip: !cartId,
    });

    useEffect(() => {
        const initCart = async () => {
            if (!cartId) {
                const { data } = await createCart();
                const newCartId = data.createEmptyCart;
                localStorage.setItem('cart_id', newCartId);
                setCartId(newCartId);
            }
        };
        initCart();
    }, [cartId, createCart]);

    const addToCart = async (sku: string, quantity: number) => {
        if (!cartId) return;
        await addProductsMutation({
            variables: { cartId, cartItems: [{ sku, quantity }] },
        });
        refetch();
    };

    return {
        cart: cartData?.cart,
        addToCart,
        loading,
        itemCount: cartData?.cart?.items?.length || 0,
    };
};

Custom hooks encapsulate GraphQL interactions. Cart ID persists in localStorage for cross-session continuity.

Service Worker Configuration

// src/service-worker.ts
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate, CacheFirst } from 'workbox-strategies';

// Precache build files
precacheAndRoute(self.__WB_MANIFEST);

// Cache product images
registerRoute(
    ({ url }) => url.pathname.startsWith('/media/catalog/product/'),
    new CacheFirst({
        cacheName: 'product-images',
        plugins: [
            new ExpirationPlugin({
                maxEntries: 1000,
                maxAgeSeconds: 30 * 24 * 60 * 60, // 30 days
            }),
        ],
    })
);

// Cache GraphQL responses
registerRoute(
    ({ url }) => url.pathname === '/graphql',
    new StaleWhileRevalidate({
        cacheName: 'graphql-responses',
        plugins: [
            new ExpirationPlugin({
                maxEntries: 50,
                maxAgeSeconds: 5 * 60, // 5 minutes
            }),
        ],
    })
);

// Offline fallback
self.addEventListener('install', (event) => {
    event.waitUntil(
        caches.open('offline-fallback').then((cache) => {
            return cache.add('/offline.html');
        })
    );
});

Push Notifications

// src/utils/pushNotifications.ts
export const requestNotificationPermission = async (): Promise<string | null> => {
    if (!('Notification' in window)) {
        return null;
    }

    const permission = await Notification.requestPermission();

    if (permission === 'granted') {
        const registration = await navigator.serviceWorker.ready;
        const subscription = await registration.pushManager.subscribe({
            userVisibleOnly: true,
            applicationServerKey: process.env.REACT_APP_VAPID_KEY,
        });

        await fetch('/rest/V1/pushnotification/subscribe', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(subscription),
        });

        return JSON.stringify(subscription);
    }

    return null;
};

Apollo Client Cache Configuration

// src/graphql/client.ts
import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createHttpLink({
    uri: process.env.REACT_APP_GRAPHQL_ENDPOINT,
});

const authLink = setContext((_, { headers }) => {
    const token = localStorage.getItem('auth_token');
    return {
        headers: {
            ...headers,
            authorization: token ? `Bearer ${token}` : '',
        },
    };
});

export const client = new ApolloClient({
    link: authLink.concat(httpLink),
    cache: new InMemoryCache({
        typePolicies: {
            Query: {
                fields: {
                    products: {
                        keyArgs: ['search', 'filter', 'sort'],
                        merge(existing, incoming) {
                            return incoming;
                        },
                    },
                },
            },
        },
    }),
});

Service workers cache static assets and GraphQL responses. Apollo Client manages the client-side data cache with type policies.

Business Requirements Context

Who is the Customer?

Headless Magento targets organizations that need front-end flexibility beyond what Luma/Hyva themes provide:

• Omnichannel retailers needing consistent UX across web, mobile app, kiosk, and in-store terminals
• Brands investing in custom UX where design agency deliverables must be implemented without Magento theme constraints
• Marketplace operators requiring micro-frontend architecture for independent team deployments
• International retailers needing multi-locale, multi-currency storefronts with region-specific checkout flows
• Mobile-first businesses where PWA performance on 3G networks is critical for conversion

What Problem Does This Solve?

1. Frontend velocity: Decoupled frontend deploys independently; no Magento static deployment bottleneck (reduces deploy time from 15-30 min to < 2 min)
2. Performance: React SSR/SSG achieves LCP < 1.5s vs 3-5s for Luma on mobile
3. Developer experience: TypeScript, hot reload, modern tooling attracts better talent (reduces hiring difficulty by 40-60%)
4. Multi-channel: Same GraphQL API powers web, mobile app, and in-store POS
5. Scalability: Frontend scales on CDN/serverless independently of Magento PHP backend

Architecture Decisions

Decision 1: React + Next.js vs Vue + Nuxt vs Vanilla PWA

Decision 2: GraphQL vs REST for API Layer

Decision 3: Deployment Architecture

Decision 4: State Management

Production Deployment Checklist

Pre-Deployment

• Run full E2E test suite (Cypress/Playwright)
• Verify all GraphQL queries pass schema validation
• Test SSR renders correctly (no hydration mismatches)
• Verify service worker registration and caching
• Test PWA installability on iOS and Android
• Load test frontend at 3x expected traffic
• Verify CSP headers allow all required domains
• Test checkout flow end-to-end with real payment
• Verify Magento GraphQL endpoint rate limiting is configured
• Test offline fallback page loads correctly

Deployment

• Deploy frontend to CDN/serverless (zero-downtime)
• Deploy backend changes during maintenance window
• Verify GraphQL endpoint is accessible from frontend domain
• Clear Apollo Client CDN cache if schema changed
• Update service worker version (cache busting)
• Run smoke tests against production frontend

Post-Deployment

• Monitor frontend performance (LCP, FID, CLS)
• Check GraphQL query latency in Magento
• Verify cart creation and checkout flow
• Monitor error rates in Sentry/LogRocket
• Check push notification delivery
• Validate SEO metadata renders in SSR

Monitoring and Alerting

Frontend Metrics (Vercel Analytics / Web Vitals)

LCP (Largest Contentful Paint)     → Target < 2.5s
FID (First Input Delay)            → Target < 100ms
CLS (Cumulative Layout Shift)      → Target < 0.1
TTFB (Time to First Byte)          → Target < 200ms
GraphQL Query Duration (p95)       → Target < 500ms

Backend Metrics (Magento + GraphQL)

GraphQL Query Response Time         → Grafana dashboard
MySQL Query Time for product/catalog → slow_query_log
Redis Cache Hit Ratio               → Target > 90%
Elasticsearch Query Latency         → Target < 100ms

Alerting Thresholds

Cost Estimation

Development Cost

Infrastructure Cost (Monthly)

Annual TCO Comparison

Headless has higher initial cost but lower long-term maintenance. Break-even occurs in month 14-18.