FrenoCorp/plans/FRE-620-event-taxonomy.md

# 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`