E-commerce Schema Cleanup with Migration Plan

EVENT SCHEMA CLEANUP PLAN

CURRENT STATE AUDIT

Duplicate Events Found:

Total duplicates: 6 events → 2 standardized events
Estimated cleanup effort: 1-2 weeks

STANDARDIZED SCHEMA

NAMING CONVENTION: object_action (snake_case, past tense)

CATEGORY: CART

CATEGORY: CHECKOUT

CATEGORY: ORDER

MIGRATION PLAN

Phase 1: Add Standardized Events (Week 1)

• Deploy new tracking code alongside existing events
• Both old and new events fire simultaneously
• Validate new events appear in Mixpanel

Phase 2: Dashboard Migration (Week 2)

• Create new funnels using standardized events
• Run old and new dashboards in parallel
• Compare metrics to ensure parity
• Get team sign-off on new dashboards

Phase 3: Code Cleanup (Week 3)

• Remove old tracking calls from codebase
• Archive old dashboards (keep for reference)
• Document deprecated event names

CRITICAL: Do NOT delete events from Mixpanel - historical data must remain intact.

DUPLICATE EVENT MAPPING

Old Events → New Standardized Events:

Cart Events:

• add_to_cart → cart_item_added
• AddToCart → cart_item_added
• cart_item_add → cart_item_added

Checkout Events:

• checkout_start → checkout_started
• CheckoutStarted → checkout_started
• checkout_initiated → checkout_started

MIXPANEL IMPLEMENTATION

// analytics/events.ts
export const TrackingEvents = {
  CART_ITEM_ADDED: 'cart_item_added',
  CART_ITEM_REMOVED: 'cart_item_removed',
  CART_VIEWED: 'cart_viewed',
  CHECKOUT_STARTED: 'checkout_started',
  CHECKOUT_STEP_COMPLETED: 'checkout_step_completed',
  ORDER_COMPLETED: 'order_completed',
  ORDER_FAILED: 'order_failed',
} as const;

export const TrackingProperties = {
  PRODUCT_ID: 'product_id',
  CART_VALUE_TOTAL: 'cart_value_total',
  CART_ITEM_COUNT: 'cart_item_count',
  ORDER_VALUE: 'order_value',
} as const;

// Helper for consistent tracking
export function trackEvent(
  event: typeof TrackingEvents[keyof typeof TrackingEvents],
  properties: Record<string, any>
) {
  mixpanel.track(event, {
    ...properties,
    event_schema_version: '2.0',
  });
}

// Usage
trackEvent(TrackingEvents.CART_ITEM_ADDED, {
  product_id: product.id,
  quantity: 1,
  cart_value_total: cart.total,
});

PROPERTY MAPPING

Old properties to standardize:

GOVERNANCE PROCESS (4-person team)

Adding new events:

1. Developer proposes event in PR description
2. Check if similar event exists (search events.ts)
3. Follow object_action naming convention
4. Peer review: second developer approves event name
5. Merge only after approval

Monthly review (first Monday):

1. Export event list from Mixpanel
2. Compare to events.ts constants
3. Identify any rogue events not in constants
4. Team reviews: keep, consolidate, or deprecate

CLEANUP CHECKLIST

Week 1:
[ ] Create analytics/events.ts constants file
[ ] Find all instances of old event names in codebase
[ ] Add standardized tracking alongside old events
[ ] Deploy and verify both appear in Mixpanel

Week 2:
[ ] Create new dashboards using new events
[ ] Compare metrics: old vs new
[ ] Get team approval on new dashboards

Week 3:
[ ] Remove old tracking code from codebase
[ ] Archive old dashboards
[ ] Update team documentation