@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/ecommerce/cart-architecture-patterns.md

@@ -0,0 +1,300 @@
+# Cart Architecture Patterns
+
+> Server-side cart management, state synchronization, guest-to-user cart merging, and constraint verification for AI-generated e-commerce code.
+
+**When to use:** Building any shopping cart system — from simple single-product checkout to multi-vendor marketplace carts.
+**Stack:** Node.js/Express, React/Next.js, PostgreSQL/MySQL
+
+---
+
+## Architecture Decision: Where Does the Cart Live?
+
+### Option 1: Server-Side Cart (Recommended for most apps)
+
+```
+Client (React)         Server (Express)         Database
+┌──────────┐          ┌──────────────┐          ┌────────┐
+│ Cart UI  │──POST───▶│ Cart API     │──INSERT──▶│ carts  │
+│ (display │◀─JSON────│ /api/cart    │◀─SELECT───│ items  │
+│  only)   │          │              │           │        │
+└──────────┘          └──────────────┘          └────────┘
+```
+
+**Pros:** Single source of truth, survives page refresh/device switch, supports cart abandonment tracking
+**Cons:** Every cart action requires API call, slightly slower UX without optimistic updates
+**Use when:** Multi-device support needed, cart abandonment emails, server-side price validation required
+
+### Option 2: Client-Side Cart (Simple use cases only)
+
+```
+Client (React)                     Server (Express)
+┌──────────────────┐              ┌──────────────┐
+│ Cart in          │──POST───────▶│ Checkout only │
+│ localStorage/    │  (checkout)  │ /api/checkout │
+│ React Context    │              └──────────────┘
+└──────────────────┘
+```
+
+**Pros:** Instant UI, no API calls for cart operations, works offline
+**Cons:** Lost on browser clear, no cross-device, no abandonment tracking, vulnerable to price manipulation
+**Use when:** Simple single-page apps, digital downloads, no cart abandonment needed
+
+### Option 3: Hybrid (Best UX)
+
+```
+Client reads from local cache (fast)
+Client writes through server API (safe)
+Server is source of truth
+Local cache is optimistic preview
+```
+
+**Use when:** You want instant UX AND server-side safety.
+
+---
+
+## Database Schema
+
+```sql
+-- Carts table (one per user or session)
+CREATE TABLE carts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id),       -- NULL for guest carts
+  session_token VARCHAR(255),               -- For guest identification
+  status VARCHAR(20) DEFAULT 'active',      -- active | merged | abandoned | converted
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  expires_at TIMESTAMP DEFAULT NOW() + INTERVAL '30 days',
+  CONSTRAINT chk_cart_owner CHECK (user_id IS NOT NULL OR session_token IS NOT NULL)
+);
+
+-- Cart items
+CREATE TABLE cart_items (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  cart_id UUID NOT NULL REFERENCES carts(id) ON DELETE CASCADE,
+  product_id UUID NOT NULL REFERENCES products(id),
+  variant_id UUID REFERENCES product_variants(id),  -- Size, color, etc.
+  quantity INTEGER NOT NULL DEFAULT 1 CHECK (quantity > 0),
+  price_at_add DECIMAL(10,2) NOT NULL,  -- Snapshot price when added
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(cart_id, product_id, variant_id)  -- One entry per product+variant
+);
+
+-- Indexes
+CREATE INDEX idx_carts_user ON carts(user_id) WHERE user_id IS NOT NULL;
+CREATE INDEX idx_carts_session ON carts(session_token) WHERE session_token IS NOT NULL;
+CREATE INDEX idx_carts_status ON carts(status);
+CREATE INDEX idx_cart_items_cart ON cart_items(cart_id);
+```
+
+---
+
+## API Endpoints
+
+```javascript
+// GET /api/cart — Get current cart
+router.get('/cart', async (req, res) => {
+  const cart = await getOrCreateCart(req.user?.id, req.sessionToken);
+  const items = await getCartItems(cart.id);
+
+  // Validate prices are still current
+  const validated = await validateCartPrices(items);
+
+  res.json({
+    cart_id: cart.id,
+    items: validated.items,
+    price_changes: validated.changes,  // Alert user if prices changed
+    subtotal: validated.subtotal,
+    item_count: validated.itemCount,
+  });
+});
+
+// POST /api/cart/items — Add item
+router.post('/cart/items', async (req, res) => {
+  const { product_id, variant_id, quantity } = req.body;
+
+  // ALWAYS validate price server-side
+  const product = await getProduct(product_id);
+  if (!product || !product.is_active) {
+    return res.status(404).json({ error: 'Product not available' });
+  }
+
+  // Check stock
+  const available = await checkStock(product_id, variant_id, quantity);
+  if (!available) {
+    return res.status(409).json({ error: 'Insufficient stock', available: available.count });
+  }
+
+  const cart = await getOrCreateCart(req.user?.id, req.sessionToken);
+  const item = await addToCart(cart.id, product_id, variant_id, quantity, product.price);
+
+  res.json({ item, cart_total: await getCartTotal(cart.id) });
+});
+
+// PATCH /api/cart/items/:id — Update quantity
+router.patch('/cart/items/:id', async (req, res) => {
+  const { quantity } = req.body;
+  if (quantity < 1) {
+    return res.status(400).json({ error: 'Quantity must be at least 1' });
+  }
+  // Re-check stock at new quantity
+  const item = await getCartItem(req.params.id);
+  const available = await checkStock(item.product_id, item.variant_id, quantity);
+  if (!available) {
+    return res.status(409).json({ error: 'Insufficient stock' });
+  }
+  const updated = await updateCartItemQuantity(req.params.id, quantity);
+  res.json(updated);
+});
+
+// DELETE /api/cart/items/:id — Remove item
+router.delete('/cart/items/:id', async (req, res) => {
+  await removeCartItem(req.params.id);
+  res.json({ removed: true });
+});
+```
+
+---
+
+## Cart Merge on Login
+
+When a guest user logs in, their anonymous cart must merge with their account cart:
+
+```javascript
+async function mergeCartsOnLogin(userId, sessionToken) {
+  const guestCart = await getCartBySession(sessionToken);
+  const userCart = await getCartByUser(userId);
+
+  if (!guestCart || guestCart.items.length === 0) return userCart;
+  if (!userCart) {
+    // Simple case: assign guest cart to user
+    await db.query('UPDATE carts SET user_id = $1, session_token = NULL WHERE id = $2',
+      [userId, guestCart.id]);
+    return guestCart;
+  }
+
+  // Merge: guest items into user cart
+  for (const guestItem of guestCart.items) {
+    const existingItem = userCart.items.find(
+      i => i.product_id === guestItem.product_id && i.variant_id === guestItem.variant_id
+    );
+
+    if (existingItem) {
+      // Same product: take higher quantity (guest was shopping more recently)
+      const newQty = Math.max(existingItem.quantity, guestItem.quantity);
+      await updateCartItemQuantity(existingItem.id, newQty);
+    } else {
+      // New product: add to user cart
+      await addToCart(userCart.id, guestItem.product_id, guestItem.variant_id,
+        guestItem.quantity, guestItem.price_at_add);
+    }
+  }
+
+  // Mark guest cart as merged
+  await db.query("UPDATE carts SET status = 'merged' WHERE id = $1", [guestCart.id]);
+
+  return await getCartByUser(userId);
+}
+```
+
+---
+
+## Price Validation at Checkout
+
+Never trust the cart's stored prices at checkout time — always re-validate:
+
+```javascript
+async function validateCartForCheckout(cartId) {
+  const items = await getCartItems(cartId);
+  const issues = [];
+
+  for (const item of items) {
+    const currentProduct = await getProduct(item.product_id);
+
+    // Product still exists and is active?
+    if (!currentProduct || !currentProduct.is_active) {
+      issues.push({ item_id: item.id, type: 'unavailable', message: `${item.name} is no longer available` });
+      continue;
+    }
+
+    // Price changed?
+    if (currentProduct.price !== item.price_at_add) {
+      issues.push({
+        item_id: item.id, type: 'price_change',
+        old_price: item.price_at_add, new_price: currentProduct.price,
+        message: `Price changed from $${item.price_at_add} to $${currentProduct.price}`
+      });
+    }
+
+    // Still in stock?
+    const stock = await checkStock(item.product_id, item.variant_id, item.quantity);
+    if (!stock.available) {
+      issues.push({
+        item_id: item.id, type: 'stock',
+        requested: item.quantity, available: stock.count,
+        message: `Only ${stock.count} available (you have ${item.quantity})`
+      });
+    }
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+```
+
+---
+
+## Session Token Middleware
+
+```javascript
+function cartSessionMiddleware(req, res, next) {
+  // Authenticated users use their user ID
+  if (req.user) {
+    req.cartIdentifier = { user_id: req.user.id };
+    return next();
+  }
+
+  // Guest users get a session token
+  let sessionToken = req.cookies?.cart_session;
+  if (!sessionToken) {
+    sessionToken = crypto.randomUUID();
+    res.cookie('cart_session', sessionToken, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      maxAge: 30 * 24 * 60 * 60 * 1000,  // 30 days
+    });
+  }
+  req.cartIdentifier = { session_token: sessionToken };
+  req.sessionToken = sessionToken;
+  next();
+}
+```
+
+---
+
+## Constraint Verification Checklist
+
+Before marking any cart feature complete:
+
+```
+□ Prices validated server-side (never from client)
+□ Stock checked before adding and at checkout
+□ Race condition handled (two users buy last item)
+□ Cart expires after configurable period (default 30 days)
+□ Guest cart merges correctly on login
+□ Price changes shown to user before checkout
+□ Unavailable products removed/flagged at checkout
+□ Quantity limits enforced (min 1, max per product policy)
+□ Cart total calculated server-side (not client sum)
+□ Session token is httpOnly, secure, sameSite
+```
+
+---
+
+## Sources
+
+- ShoppingComp (arXiv:2511.22978) — LLM Shopping Cart Benchmark (Nov 2025)
+- WebMall (arXiv:2508.13024) — Multi-Shop E-Commerce Agent Benchmark (Aug 2025)
+- ShoppingBench (arXiv:2508.04266) — Intent-Grounded Shopping Agent Benchmark (Aug 2025)
+- Adobe Commerce: `mergeCarts` GraphQL mutation reference
+- WooCommerce: Cart data flow documentation (2025)

package/skills-library/ecommerce/cart-item-count-indicator.md

@@ -0,0 +1,264 @@
+# Cart Item Count Indicator
+
+## Problem Statement
+Users need visual feedback when they add items to their cart. Industry standard (Amazon, Shopify) shows a badge with the number of items directly on the cart icon in the main navigation.
+
+## Solution Overview
+Implement a real-time cart count badge that:
+1. Shows the number of items in the cart on the cart icon
+2. Updates automatically when items are added/removed
+3. Fetches count from backend API
+4. Displays elegantly with a red badge for visibility
+
+## Implementation
+
+### 1. Backend - Cart Count Endpoint
+
+#### Controller Function (`server/controllers/cartController.js`)
+```javascript
+/**
+ * Get cart item count
+ * @route GET /api/cart/count
+ * @access Private
+ */
+export const getCartCount = async (req, res) => {
+  try {
+    const userId = req.user.id;
+
+    const result = await sql`
+      SELECT COUNT(*)::int as count
+      FROM cart_items ci
+      JOIN products p ON p.id = ci.product_id
+      WHERE ci.user_id = ${userId}
+        AND p.deleted_at IS NULL
+        AND p.status = 'published'
+    `;
+
+    res.json({
+      success: true,
+      count: result[0]?.count || 0
+    });
+  } catch (error) {
+    console.error('❌ [Get Cart Count Error]:', error);
+    res.status(500).json({
+      success: false,
+      message: 'Error fetching cart count',
+      count: 0
+    });
+  }
+};
+```
+
+#### Route Definition (`server/routes/cartRoutes.js`)
+```javascript
+import { getCartCount } from '../controllers/cartController.js';
+
+// Add route BEFORE the generic GET '/' route to avoid conflicts
+router.get('/count', auth, getCartCount);
+```
+
+### 2. Frontend - Header Component
+
+#### State and Functions (`client/src/components/layout/Header.jsx`)
+```javascript
+const Header = () => {
+  const [cartCount, setCartCount] = useState(0);
+  const { isAuthenticated } = useSelector((state) => state.auth);
+  const location = useLocation();
+
+  // Fetch cart count
+  useEffect(() => {
+    if (isAuthenticated) {
+      fetchCartCount();
+    } else {
+      setCartCount(0);
+    }
+  }, [isAuthenticated, location.pathname]);
+
+  const fetchCartCount = async () => {
+    try {
+      const { data } = await axios.get('/api/cart/count');
+      setCartCount(data.count || 0);
+    } catch (error) {
+      console.error('Failed to fetch cart count:', error);
+      setCartCount(0);
+    }
+  };
+```
+
+#### Visual Badge Display
+```javascript
+{/* Shopping Cart Icon */}
+{isAuthenticated && (
+  <Link
+    to="/cart"
+    className="relative p-2 text-gray-600 hover:text-gray-900 transition-colors duration-200"
+  >
+    <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
+            d="M3 3h2l.4 2M7 13h10l4-8H5.4M7 13L5.4 5M7 13l-2.293 2.293c-.63.63-.184 1.707.707 1.707H17m0 0a2 2 0 100 4 2 2 0 000-4zm-8 2a2 2 0 11-4 0 2 2 0 014 0z" />
+    </svg>
+    {cartCount > 0 && (
+      <span className="absolute -top-1 -right-1 h-5 w-5 bg-red-500 text-white text-xs font-bold rounded-full flex items-center justify-center">
+        {cartCount > 99 ? '99+' : cartCount}
+      </span>
+    )}
+  </Link>
+)}
+```
+
+### 3. Real-Time Updates
+
+To ensure the cart count updates when items are added/removed:
+
+#### After Adding to Cart
+```javascript
+const handleAddToCart = async (productId) => {
+  try {
+    await axios.post('/api/cart', { product_id: productId });
+
+    // Trigger cart count refresh
+    await fetchCartCount();
+
+    toast.success('Added to cart!');
+  } catch (error) {
+    toast.error('Failed to add to cart');
+  }
+};
+```
+
+#### After Removing from Cart
+```javascript
+const handleRemoveFromCart = async (itemId) => {
+  try {
+    await axios.delete(`/api/cart/${itemId}`);
+
+    // Update cart count in header
+    await fetchCartCount();
+
+    toast.success('Removed from cart');
+  } catch (error) {
+    toast.error('Failed to remove item');
+  }
+};
+```
+
+## Design Decisions
+
+### Badge Styling
+- **Red background** (`bg-red-500`): High visibility, industry standard for notifications
+- **Circular shape** (`rounded-full`): Clean, modern look
+- **Absolute positioning**: Overlays on top-right of cart icon
+- **Small size** (`h-5 w-5`): Non-intrusive but visible
+- **White text**: Maximum contrast with red background
+
+### Performance Optimizations
+1. **Conditional fetching**: Only fetch when authenticated
+2. **Location-based refresh**: Update count when navigating (useful after checkout)
+3. **Error handling**: Gracefully default to 0 on errors
+4. **SQL optimization**: Direct COUNT with JOIN for accuracy
+
+### UX Considerations
+1. **99+ display**: Prevents badge from getting too wide with large numbers
+2. **Hide when 0**: Don't show badge when cart is empty
+3. **Smooth transitions**: CSS transitions on hover states
+4. **Responsive**: Works on both desktop and mobile views
+
+## Testing
+
+### Manual Testing
+1. **Add item to cart**: Badge should appear/increment
+2. **Remove item**: Badge should decrement/disappear
+3. **Clear cart**: Badge should disappear
+4. **Login/Logout**: Badge should appear/disappear appropriately
+5. **Page refresh**: Count should persist
+
+### API Testing
+```bash
+# Test cart count endpoint
+curl -X GET http://localhost:5000/api/cart/count \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# Expected response:
+{
+  "success": true,
+  "count": 3
+}
+```
+
+## Common Issues and Solutions
+
+### Issue: Count not updating after adding item
+**Solution**: Ensure `fetchCartCount()` is called after successful cart operations
+
+### Issue: Badge overlapping with other elements
+**Solution**: Parent element needs `relative` positioning
+
+### Issue: Count showing wrong number
+**Solution**: Check SQL query joins products table and filters by status
+
+## Alternative Implementations
+
+### 1. Redux State Management
+Instead of local component state, use Redux:
+```javascript
+// Redux slice
+const cartSlice = createSlice({
+  name: 'cart',
+  initialState: { count: 0 },
+  reducers: {
+    setCartCount: (state, action) => {
+      state.count = action.payload;
+    }
+  }
+});
+```
+
+### 2. WebSocket Real-Time Updates
+For multi-tab synchronization:
+```javascript
+socket.on('cart-updated', (data) => {
+  if (data.userId === currentUserId) {
+    setCartCount(data.count);
+  }
+});
+```
+
+### 3. Context API
+For sharing cart count across components:
+```javascript
+const CartContext = createContext();
+
+export const CartProvider = ({ children }) => {
+  const [cartCount, setCartCount] = useState(0);
+  return (
+    <CartContext.Provider value={{ cartCount, setCartCount }}>
+      {children}
+    </CartContext.Provider>
+  );
+};
+```
+
+## Industry Standards Reference
+
+### Amazon Style
+- Red badge with white number
+- Shows total item count (not unique products)
+- Updates instantly on add/remove
+
+### Shopify Style
+- Often shows slide-out panel with items
+- Badge shows item count
+- May include mini cart preview on hover
+
+### Best Practices
+1. **Instant feedback**: Update immediately, even before server confirms
+2. **Optimistic updates**: Show change, rollback on error
+3. **Accessibility**: Include aria-label for screen readers
+4. **Mobile-friendly**: Ensure touch targets are adequate size
+
+---
+
+**Last Updated**: October 31, 2024
+**Tested With**: React 18, Node.js/Express, PostgreSQL
+**Author**: Claude (Anthropic)