From b1cfce3661afabd1a75dd5452644a8ace55d461c Mon Sep 17 00:00:00 2001
From: Michael Freno <michaelt.freno@gmail.com>
Date: Thu, 14 May 2026 21:17:45 -0400
Subject: [PATCH] docs: Add Mixpanel analytics configuration documentation

- Documents existing Mixpanel implementation
- Full event taxonomy from shared-analytics package
- Frontend integration via useAnalytics hook
- Required actions for Mixpanel account setup
---
 docs/MIXPANEL_ANALYTICS.md | 57 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/MIXPANEL_ANALYTICS.md

diff --git a/docs/MIXPANEL_ANALYTICS.md b/docs/MIXPANEL_ANALYTICS.md
new file mode 100644
index 0000000..58e7dc2
--- /dev/null
+++ b/docs/MIXPANEL_ANALYTICS.md
@@ -0,0 +1,57 @@
+# ShieldAI Mixpanel Analytics Configuration
+
+## Current Implementation Status
+
+✅ **Already Implemented:**
+
+### Backend (packages/shared-analytics)
+- Full MixpanelService with Segment analytics integration
+- Event taxonomy defined in `EventType` enum:
+  - User events: `user_signed_up`, `user_logged_in`, `user_upgraded`, etc.
+  - Subscription events: `subscription_created`, `subscription_cancelled`, etc.
+  - Product-specific events: DarkWatch, VoicePrint, SpamShield events
+- User identification and group tracking
+- KPI definitions (MAU, MRR, conversion rate, churn, etc.)
+
+### Frontend (packages/web)
+- Analytics hook (`useAnalytics.ts`) with:
+  - Mixpanel initialization via `VITE_MIXPANEL_TOKEN`
+  - Event tracking (`trackEvent`)
+  - Page view tracking (`trackPageView`)
+  - Waitlist signup tracking (`trackWaitlistSignup`)
+- GA4, Meta Pixel, and LinkedIn Insight integration
+
+## Required Actions
+
+### 1. Create Mixpanel Project (Manual - Requires Account)
+- Sign up for Mixpanel at https://mixpanel.com
+- Create project: "ShieldAI"
+- Get project token from Project Settings → Project Token
+
+### 2. Configure Environment Variables
+```bash
+# Backend (.env)
+MIXPANEL_TOKEN=<your-mixpanel-token>
+MIXPANEL_API_SECRET=<optional-api-secret>
+
+# Frontend (.env)
+VITE_MIXPANEL_TOKEN=<your-mixpanel-token>
+```
+
+### 3. Event Taxonomy Documentation
+See `packages/shared-analytics/src/config/analytics.config.ts` for full event definitions.
+
+### 4. User Property Definitions
+Standard properties tracked:
+- `userId`: User identifier
+- `sessionId`: Session identifier  
+- `platform`: web, mobile, desktop, api
+- `version`: App version
+- `environment`: development, production, staging
+
+## Integration Points
+
+- `DarkWatch`: Exposure detection events
+- `SpamShield`: Spam detection and blocking events
+- `VoicePrint`: Voice enrollment and analysis events
+- `Waitlist`: Signup tracking with source attribution