Auto-commit 2026-04-27 12:34

2026-04-27 12:34:30 -04:00
parent bef1d7f829
commit 9e3a54f508
12 changed files with 1025 additions and 5 deletions
--- a/plans/FRE-620-event-taxonomy.md
+++ b/plans/FRE-620-event-taxonomy.md
@@ -0,0 +1,258 @@
+# Analytics Event Taxonomy
+
+## Overview
+
+This document defines the event taxonomy for FrenoCorp's analytics implementation across Mixpanel, GA4, and Stripe. Events are organized by category and mapped to each platform.
+
+## Event Categories
+
+### 1. User Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `user_signedup` | ✅ | `sign_up` | `customer.created` | New user registration |
+| `user_signedin` | ✅ | `login` | - | User login |
+| `user_signedout` | ✅ | `logout` | - | User logout |
+| `user_profile_updated` | ✅ | `update_user` | `customer.updated` | Profile changes |
+
+**Properties:**
+- `user_id` (string)
+- `email` (string)
+- `signup_method` (string: 'email', 'google', 'github')
+- `plan_tier` (string: 'free', 'pro', 'enterprise')
+- `timestamp` (ISO 8601)
+
+### 2. Project Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `project_created` | ✅ | `project_create` | - | New project created |
+| `project_updated` | ✅ | `project_update` | - | Project modifications |
+| `project_deleted` | ✅ | `project_delete` | - | Project removal |
+| `project_shared` | ✅ | `share_project` | - | Sharing with collaborators |
+
+**Properties:**
+- `project_id` (string)
+- `project_name` (string)
+- `template_id` (string, optional)
+- `collaborator_count` (number)
+- `timestamp` (ISO 8601)
+
+### 3. Screenplay Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `screenplay_created` | ✅ | `screenplay_create` | - | New screenplay |
+| `screenplay_updated` | ✅ | `screenplay_update` | - | Screenplay modification |
+| `screenplay_exported` | ✅ | `screenplay_export` | - | Export to PDF/Word |
+| `screenplay_saved` | ✅ | `save_screenplay` | - | Auto-save event |
+
+**Properties:**
+- `screenplay_id` (string)
+- `project_id` (string)
+- `page_count` (number)
+- `word_count` (number)
+- `export_format` (string, optional: 'pdf', 'docx', 'fdx')
+- `timestamp` (ISO 8601)
+
+### 4. Collaboration Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `invitation_sent` | ✅ | `send_invitation` | - | Invite sent to collaborator |
+| `invitation_accepted` | ✅ | `accept_invitation` | - | Collaborator joined |
+| `collaboration_started` | ✅ | `start_collaboration` | - | Real-time editing began |
+| `collaboration_updated` | ✅ | `update_collaboration` | - | Collaboration settings changed |
+
+**Properties:**
+- `project_id` (string)
+- `inviter_id` (string)
+- `invitee_email` (string)
+- `permission_level` (string: 'view', 'edit', 'admin')
+- `timestamp` (ISO 8601)
+
+### 5. Export/Import Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `export_completed` | ✅ | `export_complete` | - | Export finished |
+| `export_failed` | ✅ | `export_error` | - | Export error |
+| `import_completed` | ✅ | `import_complete` | - | Import finished |
+| `import_failed` | ✅ | `import_error` | - | Import error |
+
+**Properties:**
+- `export_format` (string: 'pdf', 'docx', 'fdx', 'txt')
+- `file_size_bytes` (number)
+- `duration_ms` (number)
+- `success` (boolean)
+- `error_message` (string, optional)
+- `timestamp` (ISO 8601)
+
+### 6. Subscription/Payment Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `subscription_started` | ✅ | `begin_checkout` | `subscription.created` | Subscription initiated |
+| `subscription_renewed` | ✅ | `purchase` | `invoice.payment_succeeded` | Subscription renewed |
+| `subscription_cancelled` | ✅ | `purchase` | `subscription.deleted` | Subscription cancelled |
+| `payment_succeeded` | ✅ | `purchase` | `payment_intent.succeeded` | Payment successful |
+| `payment_failed` | ✅ | `purchase` | `payment_intent.payment_failed` | Payment failed |
+| `upgrade_attempted` | ✅ | `select_item` | `customer.updated` | Plan upgrade |
+
+**Properties:**
+- `subscription_id` (string)
+- `customer_id` (string)
+- `plan_tier` (string: 'free', 'pro', 'enterprise')
+- `amount` (number, in cents)
+- `currency` (string: 'USD', 'EUR', etc.)
+- `payment_method` (string: 'card', 'paypal', 'bank_transfer')
+- `duration_months` (number)
+- `timestamp` (ISO 8601)
+
+### 7. E-commerce Events (GA4 Enhanced)
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `view_pricing_page` | ✅ | `view_item` | - | Viewed pricing |
+| `add_to_cart` | ✅ | `add_to_cart` | - | Selected plan |
+| `begin_checkout` | ✅ | `begin_checkout` | - | Started checkout |
+| `purchase` | ✅ | `purchase` | `invoice.payment_succeeded` | Completed purchase |
+
+**E-commerce Item Properties:**
+```typescript
+interface GA4EcommerceItem {
+  item_id: string;           // Plan SKU (e.g., 'pro_monthly')
+  item_name: string;         // Display name (e.g., 'Pro Monthly')
+  item_category: string;     // 'subscription_tier'
+  price: number;             // Price in cents
+  quantity: number;          // Usually 1 for subscriptions
+  currency: string;          // 'USD', 'EUR', etc.
+}
+```
+
+### 8. Engagement Events
+
+| Event Name | Mixpanel | GA4 | Stripe | Description |
+|------------|----------|-----|--------|-------------|
+| `page_view` | ✅ | `page_view` | - | Page navigation |
+| `search` | ✅ | `search` | - | Search performed |
+| `feature_used` | ✅ | `feature_click` | - | Feature interaction |
+| `help_viewed` | ✅ | `view_help` | - | Help documentation |
+
+**Properties:**
+- `page_name` (string)
+- `search_query` (string, optional)
+- `feature_name` (string, optional)
+- `session_id` (string)
+- `timestamp` (ISO 8601)
+
+## Platform Configuration
+
+### Mixpanel
+
+```typescript
+// Project Token: Environment variable MIXPANEL_PROJECT_TOKEN
+// Options:
+{
+  debug: process.env.NODE_ENV === 'development',
+  track_pageview: true,
+  persistence: 'localStorage',
+}
+```
+
+**Key Features:**
+- User identification with `identify()`
+- User properties with `people.set()`
+- Group analytics with `group()`
+- Cohort analysis support
+
+### GA4
+
+```typescript
+// Measurement ID: Environment variable GA4_MEASUREMENT_ID
+// Options:
+{
+  debug: process.env.NODE_ENV === 'development',
+  autoTrackPageViews: true,
+  autoTrackScrolls: true,
+  autoTrackOutboundLinks: true,
+}
+```
+
+**Key Features:**
+- Enhanced e-commerce tracking
+- Automatic pageview tracking
+- Scroll depth tracking
+- Outbound link tracking
+
+### Stripe
+
+```typescript
+// Configuration:
+{
+  publishableKey: process.env.STRIPE_PUBLISHABLE_KEY,
+  secretKey: process.env.STRIPE_SECRET_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  apiVersion: '2024-12-18.acacia',
+}
+```
+
+**Key Features:**
+- Customer management
+- Subscription lifecycle
+- Payment intent tracking
+- Webhook event handling
+
+## Implementation Notes
+
+### Event Naming Conventions
+
+1. **Mixpanel**: snake_case (e.g., `user_signedup`)
+2. **GA4**: snake_case for custom events, standard names for e-commerce
+3. **Stripe**: dot notation (e.g., `customer.created`)
+
+### Property Naming
+
+- Use snake_case for all property names
+- Use ISO 8601 for timestamps
+- Use lowercase for enum values
+- Include `timestamp` on all events
+
+### Data Retention
+
+- **Mixpanel**: 24 months (default), configurable
+- **GA4**: 14 months (default), configurable
+- **Stripe**: Indefinite for subscription data
+
+### Privacy Considerations
+
+- PII stored in Mixpanel: `email`, `name`
+- PII stored in GA4: User properties only (not in events)
+- PII stored in Stripe: Full customer data
+
+## Environment Variables
+
+```bash
+# Mixpanel
+MIXPANEL_PROJECT_TOKEN=
+
+# GA4
+GA4_MEASUREMENT_ID=
+
+# Stripe
+STRIPE_PUBLISHABLE_KEY=
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+```
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2026-04-27 | Initial taxonomy for FRE-620 |
+
+## Related Documents
+
+- Parent Issue: [FRE-585](/FRE/issues/FRE-585) - Analytics dashboard setup and KPI tracking
+- Implementation: `src/lib/analytics/`
+- KPI Definitions: `src/lib/analytics/kpi-service.ts`