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:

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

// 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

// 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

// 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

# 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 - Analytics dashboard setup and KPI tracking
• Implementation: src/lib/analytics/
• KPI Definitions: src/lib/analytics/kpi-service.ts