@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/ecommerce/checkout-ux-conversion.md

@@ -0,0 +1,227 @@
+# Checkout UX Conversion Patterns
+
+> Evidence-based checkout design patterns that yield up to 35% conversion lift. Template for AI agents generating checkout flows.
+
+**When to use:** Building or reviewing any checkout flow. Apply these patterns when scaffolding checkout components.
+**Stack:** React, Next.js, or any frontend framework
+
+---
+
+## The 10 Checkout Rules
+
+### 1. Guest Checkout First
+
+```jsx
+// WRONG: Force account creation before checkout
+<Button onClick={() => navigate('/register')}>Create Account to Continue</Button>
+
+// RIGHT: Guest checkout with optional account creation after purchase
+<Button onClick={() => navigate('/checkout')}>Continue as Guest</Button>
+<Button variant="secondary" onClick={() => navigate('/login')}>Sign In</Button>
+// After order confirmation:
+<p>Save your info for next time?</p>
+<Button onClick={createAccountFromOrder}>Create Account</Button>
+```
+
+**Why:** 24% of users abandon when forced to create an account (Baymard).
+
+### 2. Progress Indicator
+
+```jsx
+function CheckoutProgress({ currentStep }) {
+  const steps = ['Cart', 'Shipping', 'Payment', 'Confirm'];
+  return (
+    <div className="flex justify-between mb-8" role="progressbar">
+      {steps.map((step, i) => (
+        <div key={step} className={`flex items-center ${i <= currentStep ? 'text-blue-600' : 'text-gray-400'}`}>
+          <span className={`w-8 h-8 rounded-full flex items-center justify-center
+            ${i < currentStep ? 'bg-blue-600 text-white' : i === currentStep ? 'border-2 border-blue-600' : 'border border-gray-300'}`}>
+            {i < currentStep ? '✓' : i + 1}
+          </span>
+          <span className="ml-2 text-sm">{step}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 3. Inline Validation
+
+```jsx
+// WRONG: Validate only on submit, show all errors at top
+// RIGHT: Validate each field on blur, show error next to field
+<input
+  type="email"
+  onBlur={(e) => {
+    if (!e.target.value.includes('@')) {
+      setErrors(prev => ({ ...prev, email: 'Please enter a valid email' }));
+    } else {
+      setErrors(prev => ({ ...prev, email: null }));
+    }
+  }}
+/>
+{errors.email && <span className="text-red-500 text-sm mt-1">{errors.email}</span>}
+```
+
+### 4. Transparent Pricing (No Surprise Costs)
+
+```jsx
+function OrderSummary({ items, shipping, tax, discount }) {
+  const subtotal = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const total = subtotal + shipping + tax - discount;
+
+  return (
+    <div className="border rounded p-4">
+      <h3 className="font-bold mb-4">Order Summary</h3>
+      {items.map(item => (
+        <div key={item.id} className="flex justify-between text-sm mb-2">
+          <span>{item.name} x{item.quantity}</span>
+          <span>${(item.price * item.quantity).toFixed(2)}</span>
+        </div>
+      ))}
+      <hr className="my-2" />
+      <div className="flex justify-between text-sm">
+        <span>Subtotal</span><span>${subtotal.toFixed(2)}</span>
+      </div>
+      <div className="flex justify-between text-sm">
+        <span>Shipping</span>
+        <span>{shipping === 0 ? 'FREE' : `$${shipping.toFixed(2)}`}</span>
+      </div>
+      <div className="flex justify-between text-sm">
+        <span>Tax</span><span>${tax.toFixed(2)}</span>
+      </div>
+      {discount > 0 && (
+        <div className="flex justify-between text-sm text-green-600">
+          <span>Discount</span><span>-${discount.toFixed(2)}</span>
+        </div>
+      )}
+      <hr className="my-2" />
+      <div className="flex justify-between font-bold">
+        <span>Total</span><span>${total.toFixed(2)}</span>
+      </div>
+    </div>
+  );
+}
+```
+
+**Why:** 49% of users abandon when extra costs (shipping, tax) are shown too late (Baymard).
+
+### 5. Trust Signals Near Payment
+
+```jsx
+<div className="flex items-center gap-2 text-sm text-gray-600 mt-4">
+  <LockIcon className="w-4 h-4" />
+  <span>Secure checkout powered by Stripe</span>
+</div>
+<div className="flex gap-4 mt-2">
+  <img src="/visa.svg" alt="Visa" className="h-6" />
+  <img src="/mastercard.svg" alt="Mastercard" className="h-6" />
+  <img src="/amex.svg" alt="Amex" className="h-6" />
+</div>
+```
+
+### 6. Mobile-Optimized Touch Targets
+
+```css
+/* Minimum 44x44px touch targets (Apple HIG) */
+.checkout-button {
+  min-height: 44px;
+  min-width: 44px;
+  padding: 12px 24px;
+  font-size: 16px; /* Prevents iOS zoom on focus */
+}
+
+.checkout-input {
+  min-height: 44px;
+  font-size: 16px; /* Critical: prevents auto-zoom on iOS */
+  padding: 12px;
+}
+```
+
+### 7. Prevent Double-Submit
+
+```jsx
+function CheckoutButton({ onSubmit }) {
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleClick = async () => {
+    if (isSubmitting) return;
+    setIsSubmitting(true);
+    try {
+      await onSubmit();
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <button onClick={handleClick} disabled={isSubmitting}
+      className={`w-full py-3 rounded ${isSubmitting ? 'bg-gray-400' : 'bg-blue-600 hover:bg-blue-700'} text-white`}>
+      {isSubmitting ? 'Processing...' : 'Complete Purchase'}
+    </button>
+  );
+}
+```
+
+### 8. Address Autocomplete
+
+```jsx
+// Use browser's built-in autocomplete
+<input name="street-address" autoComplete="street-address" />
+<input name="city" autoComplete="address-level2" />
+<input name="state" autoComplete="address-level1" />
+<input name="postal-code" autoComplete="postal-code" />
+<input name="country" autoComplete="country" />
+```
+
+### 9. Edit Cart Without Leaving Checkout
+
+```jsx
+// Show editable cart summary in sidebar/drawer during checkout
+// Don't force user back to /cart page to change quantities
+<CartItem>
+  <QuantitySelector value={item.quantity}
+    onChange={(qty) => updateCartItem(item.id, qty)} />
+  <RemoveButton onClick={() => removeCartItem(item.id)} />
+</CartItem>
+```
+
+### 10. Clear Error Recovery
+
+```jsx
+// After payment failure, show clear next steps
+{paymentError && (
+  <div className="bg-red-50 border border-red-200 rounded p-4 mb-4">
+    <p className="font-medium text-red-800">Payment could not be processed</p>
+    <p className="text-sm text-red-600 mt-1">{paymentError.message}</p>
+    <p className="text-sm mt-2">You can try a different card or payment method below.</p>
+  </div>
+)}
+```
+
+---
+
+## Verification Checklist
+
+```
+□ Guest checkout available (no forced registration)
+□ Progress indicator visible
+□ Inline field validation on blur
+□ All costs shown before payment step
+□ Trust signals near payment form
+□ Touch targets ≥ 44x44px on mobile
+□ Input font-size ≥ 16px (prevents iOS zoom)
+□ Submit button disabled after click
+□ Address autocomplete attributes set
+□ Cart editable from checkout page
+□ Clear error messages on payment failure
+```
+
+---
+
+## Sources
+
+- Baymard Institute: "Current State of Checkout UX" (2025)
+- Amazon-Bench (arXiv:2508.15832) — E-Commerce Agent Safety Benchmark (Aug 2025)
+- Apple Human Interface Guidelines: Touch target sizing

package/skills-library/ecommerce/composable-commerce-selection.md

@@ -0,0 +1,166 @@
+# Composable Commerce Architecture Selection Guide
+
+> Decision tree for choosing between monolithic, headless, and composable commerce architectures based on project requirements.
+
+**When to use:** Starting a new e-commerce project or evaluating whether to migrate from a monolithic platform. Use during the planning phase to make the architecture decision explicit.
+**Stack:** Framework-agnostic (the decision determines the stack)
+
+---
+
+## Architecture Spectrum
+
+```
+Simple ◀────────────────────────────────────────────▶ Complex
+
+┌──────────┐    ┌──────────┐    ┌────────────────┐
+│ Monolithic│    │ Headless │    │  Composable    │
+│ (Shopify, │    │ (Medusa, │    │  (Mix-and-match│
+│  WooComm) │    │  Saleor) │    │   best APIs)  │
+└──────────┘    └──────────┘    └────────────────┘
+     │                │                  │
+ All-in-one      Decouple          Decouple
+ frontend +      frontend           EVERYTHING
+ backend         from backend
+```
+
+---
+
+## Decision Tree
+
+### Question 1: Who are your customers?
+
+```
+IF single storefront (web only):
+  → Monolithic or Headless both work
+IF multi-channel (web + mobile + email + kiosks):
+  → Headless or Composable (monolithic can't serve multiple frontends)
+IF B2B + B2C or marketplace:
+  → Composable (different channels have different business logic)
+```
+
+### Question 2: How fast do you need to launch?
+
+```
+IF < 2 weeks to MVP:
+  → Monolithic (Shopify, WooCommerce, Squarespace)
+IF 1-3 months:
+  → Headless (Medusa.js, Saleor, Shopify Hydrogen)
+IF 3+ months, complex requirements:
+  → Composable (custom API composition)
+```
+
+### Question 3: How custom is your business logic?
+
+```
+IF standard catalog + checkout:
+  → Monolithic (no need to reinvent)
+IF custom pricing, subscriptions, or workflows:
+  → Headless (customize backend, own frontend)
+IF unique fulfillment, multi-vendor, or complex tax rules:
+  → Composable (swap individual components)
+```
+
+### Question 4: What's your team's capability?
+
+```
+IF non-technical or small team:
+  → Monolithic (hosted, managed, minimal code)
+IF full-stack developers:
+  → Headless (you build the frontend, platform handles commerce)
+IF platform/infra team:
+  → Composable (you manage multiple services)
+```
+
+---
+
+## Platform Comparison
+
+| Feature | Shopify | Medusa.js v2 | Saleor | Composable |
+|---------|---------|-------------|--------|------------|
+| **Type** | Monolithic (+ Hydrogen headless) | Headless | Headless | Architecture pattern |
+| **Frontend** | Themes or Hydrogen (React) | Any | Any | Any |
+| **API** | REST + GraphQL | REST + JS SDK | GraphQL only | Mix |
+| **Database** | Managed | PostgreSQL | PostgreSQL | Per-service |
+| **Payments** | Shopify Payments + 100+ | Stripe module | Stripe/Adyen | Any |
+| **Self-host** | No (SaaS) | Yes (open source) | Yes (open source) | Yes |
+| **Pricing** | $29-$299/mo + transaction fees | Free (self-host) | Free (self-host) | Varies |
+| **Best for** | Quick launch, non-technical | Custom commerce, developers | GraphQL-first, multi-channel | Enterprise, multi-vendor |
+
+---
+
+## Medusa.js v2 Quick Reference
+
+Medusa 2.0 uses composable Workflows made of atomic Steps:
+
+```typescript
+// Example: Custom checkout workflow
+import { createWorkflow, createStep } from "@medusajs/workflows-sdk";
+
+const validateCartStep = createStep("validate-cart", async (input) => {
+  // Validate cart items, prices, stock
+  return { valid: true };
+});
+
+const capturePaymentStep = createStep("capture-payment", async (input) => {
+  // Capture payment via Stripe module
+  return { payment_id: "pi_xxx" };
+}, {
+  // Compensating action if later steps fail
+  compensate: async (input) => {
+    await refundPayment(input.payment_id);
+  }
+});
+
+export const checkoutWorkflow = createWorkflow("checkout", (input) => {
+  const validation = validateCartStep(input);
+  const payment = capturePaymentStep(input);
+  return { validation, payment };
+});
+```
+
+---
+
+## Saleor Quick Reference
+
+GraphQL-native, variant-based checkout:
+
+```graphql
+# Create checkout with variant IDs (not product IDs)
+mutation {
+  checkoutCreate(input: {
+    lines: [
+      { variantId: "VmFyaWFudDox", quantity: 2 }
+    ]
+    email: "customer@example.com"
+  }) {
+    checkout {
+      id
+      totalPrice { gross { amount currency } }
+    }
+    errors { field message }
+  }
+}
+```
+
+---
+
+## Recommendation by Project Type
+
+| Project Type | Recommended | Why |
+|-------------|-------------|-----|
+| Landing page + buy button | Shopify | Fastest to revenue |
+| Custom SaaS with billing | Stripe Checkout (no platform) | Direct integration |
+| Online course platform | Headless (Medusa/custom) | Custom enrollment logic |
+| Marketplace | Composable | Multi-vendor, complex fulfillment |
+| Church/nonprofit store | WooCommerce or Shopify | Low cost, familiar |
+| B2B with custom pricing | Composable | Price tiers, quotes, contracts |
+
+---
+
+## Sources
+
+- composable.com: "Composable Commerce in 2025" (2025)
+- composable.com: "Headless vs Composable Commerce" (2025)
+- Medusa.js v2 Architecture Documentation (2025)
+- Saleor API Documentation (2025)
+- Shopify Hydrogen Winter '26 Update (2025)

package/skills-library/ecommerce/ecommerce-analytics-patterns.md

@@ -0,0 +1,167 @@
+# E-Commerce Analytics & Reporting Patterns
+
+> Funnel analysis, customer lifetime value, cohort analysis, and revenue forecasting for e-commerce dashboards.
+
+**When to use:** Building admin dashboards or reporting features for e-commerce systems.
+**Stack:** PostgreSQL (window functions, CTEs), any charting library (Recharts, Chart.js)
+
+---
+
+## Core KPIs
+
+### 1. Revenue Summary
+
+```sql
+SELECT
+  DATE_TRUNC('month', created_at) as month,
+  COUNT(*) as order_count,
+  SUM(total) as revenue,
+  AVG(total) as avg_order_value,
+  COUNT(DISTINCT user_id) as unique_customers
+FROM orders
+WHERE status IN ('confirmed', 'processing', 'shipped', 'delivered')
+  AND created_at > NOW() - INTERVAL '12 months'
+GROUP BY DATE_TRUNC('month', created_at)
+ORDER BY month DESC;
+```
+
+### 2. Conversion Funnel
+
+```sql
+WITH funnel AS (
+  SELECT
+    COUNT(DISTINCT CASE WHEN event_type = 'product_viewed' THEN session_id END) as viewed,
+    COUNT(DISTINCT CASE WHEN event_type = 'item_added' THEN session_id END) as added_to_cart,
+    COUNT(DISTINCT CASE WHEN event_type = 'checkout_started' THEN session_id END) as checkout,
+    COUNT(DISTINCT CASE WHEN event_type = 'order_completed' THEN session_id END) as purchased
+  FROM cart_events
+  WHERE created_at > NOW() - INTERVAL '30 days'
+)
+SELECT
+  viewed,
+  added_to_cart,
+  ROUND(added_to_cart::numeric / NULLIF(viewed, 0) * 100, 1) as view_to_cart_pct,
+  checkout,
+  ROUND(checkout::numeric / NULLIF(added_to_cart, 0) * 100, 1) as cart_to_checkout_pct,
+  purchased,
+  ROUND(purchased::numeric / NULLIF(checkout, 0) * 100, 1) as checkout_to_purchase_pct,
+  ROUND(purchased::numeric / NULLIF(viewed, 0) * 100, 1) as overall_conversion_pct
+FROM funnel;
+```
+
+### 3. Customer Lifetime Value (CLV)
+
+```sql
+WITH customer_stats AS (
+  SELECT
+    user_id,
+    COUNT(*) as order_count,
+    SUM(total) as total_spent,
+    MIN(created_at) as first_order,
+    MAX(created_at) as last_order,
+    AVG(total) as avg_order_value
+  FROM orders
+  WHERE status NOT IN ('cancelled', 'failed', 'refunded')
+  GROUP BY user_id
+)
+SELECT
+  CASE
+    WHEN total_spent > 500 THEN 'VIP (>$500)'
+    WHEN total_spent > 200 THEN 'Regular ($200-500)'
+    WHEN total_spent > 50 THEN 'Casual ($50-200)'
+    ELSE 'New (<$50)'
+  END as customer_tier,
+  COUNT(*) as customer_count,
+  ROUND(AVG(total_spent), 2) as avg_clv,
+  ROUND(AVG(order_count), 1) as avg_orders,
+  ROUND(AVG(avg_order_value), 2) as avg_order_value,
+  ROUND(AVG(EXTRACT(EPOCH FROM last_order - first_order) / 86400), 0) as avg_lifespan_days
+FROM customer_stats
+GROUP BY 1
+ORDER BY avg_clv DESC;
+```
+
+### 4. Product Performance
+
+```sql
+SELECT
+  p.name,
+  COUNT(oi.id) as units_sold,
+  SUM(oi.total_price) as revenue,
+  ROUND(AVG(oi.unit_price), 2) as avg_price,
+  pv.stock_quantity as current_stock,
+  ROUND(COUNT(oi.id)::numeric /
+    NULLIF(EXTRACT(DAYS FROM NOW() - MIN(oi.created_at)), 0), 1) as daily_velocity
+FROM order_items oi
+JOIN products p ON p.id = oi.product_id
+LEFT JOIN product_variants pv ON pv.product_id = p.id
+JOIN orders o ON o.id = oi.order_id
+WHERE o.status NOT IN ('cancelled', 'failed')
+  AND o.created_at > NOW() - INTERVAL '30 days'
+GROUP BY p.id, p.name, pv.stock_quantity
+ORDER BY revenue DESC
+LIMIT 20;
+```
+
+### 5. Cohort Retention
+
+```sql
+WITH first_purchase AS (
+  SELECT user_id, DATE_TRUNC('month', MIN(created_at)) as cohort_month
+  FROM orders WHERE status NOT IN ('cancelled', 'failed')
+  GROUP BY user_id
+),
+monthly_activity AS (
+  SELECT
+    fp.cohort_month,
+    DATE_TRUNC('month', o.created_at) as activity_month,
+    COUNT(DISTINCT o.user_id) as active_customers
+  FROM orders o
+  JOIN first_purchase fp ON fp.user_id = o.user_id
+  WHERE o.status NOT IN ('cancelled', 'failed')
+  GROUP BY fp.cohort_month, DATE_TRUNC('month', o.created_at)
+)
+SELECT
+  cohort_month,
+  activity_month,
+  EXTRACT(MONTH FROM activity_month - cohort_month) as months_since_first,
+  active_customers,
+  ROUND(active_customers::numeric / FIRST_VALUE(active_customers)
+    OVER (PARTITION BY cohort_month ORDER BY activity_month) * 100, 1) as retention_pct
+FROM monthly_activity
+ORDER BY cohort_month, activity_month;
+```
+
+---
+
+## API Endpoints
+
+```javascript
+// GET /api/admin/analytics/summary — Dashboard overview
+router.get('/admin/analytics/summary', requireAdmin, async (req, res) => {
+  const { period = '30d' } = req.query;
+  const interval = period === '7d' ? '7 days' : period === '90d' ? '90 days' : '30 days';
+
+  const [revenue, orders, customers, topProducts] = await Promise.all([
+    getRevenueSummary(interval),
+    getOrderStats(interval),
+    getCustomerStats(interval),
+    getTopProducts(interval, 10),
+  ]);
+
+  res.json({ revenue, orders, customers, topProducts, period });
+});
+
+// GET /api/admin/analytics/funnel
+router.get('/admin/analytics/funnel', requireAdmin, async (req, res) => {
+  const funnel = await getConversionFunnel(req.query.period || '30d');
+  res.json(funnel);
+});
+```
+
+---
+
+## Sources
+
+- Internal gap analysis: GAP-ECOM-9 (E-Commerce Analytics)
+- PostgreSQL: Window functions and CTEs documentation