Overview#
This document defines privacy-compliant event schemas for the Lilith wisdom platform. All schemas follow non-PII principles, using session IDs, hashed user IDs, and aggregate metrics to protect user privacy while providing valuable analytics.
Privacy Principles#
- No Direct PII: No names, emails, or identifying information
- Hashed User IDs: Cryptographically hashed with rotating salts
- Session-Based Tracking: Temporary session identifiers for user flows
- Consent-Required: All events require explicit user consent
- Retention Limits: Automatic deletion after defined periods
- Aggregation-First: Individual events aggregated before analysis
Base Event Structure#
All events follow this base schema:
typescript
interface BaseEvent {
event_id: string; // UUID for deduplication
event_type: string; // Event type identifier
timestamp: string; // ISO 8601 timestamp
session_id: string; // Temporary session identifier
user_hash?: string; // Optional hashed user ID (if consented)
platform: 'web' | 'ios' | 'android';
version: string; // App/platform version
locale: string; // User locale (e.g., 'en-US')
timezone: string; // User timezone
}
1. Conversation & Chat Events#
ConversationStarted#
typescript
interface ConversationStartedEvent extends BaseEvent {
event_type: 'conversation.started';
persona: string; // Selected persona (zen, stoic, sufi)
conversation_id: string; // Conversation identifier
input_modality: 'text' | 'voice';
context_type?: 'course' | 'freeform' | 'reflection';
course_id?: string; // If part of course
}
MessageCompleted#
typescript
interface MessageCompletedEvent extends BaseEvent {
event_type: 'message.completed';
conversation_id: string;
message_id: string;
persona: string;
latency_ms: number; // Total response time
tokens_in: number; // Input token count
tokens_out: number; // Output token count
rag_hit_rate: number; // 0.0-1.0 retrieval success
citations_count: number; // Number of citations provided
safety_flags: string[]; // Moderation flags triggered
user_rating?: number; // 1-5 if user rated response
}
ConversationEnded#
typescript
interface ConversationEndedEvent extends BaseEvent {
event_type: 'conversation.ended';
conversation_id: string;
persona: string;
duration_ms: number; // Total conversation time
message_count: number; // Total messages exchanged
user_initiated_end: boolean; // User ended vs timeout
}
2. Learning & Course Events#
CourseStarted#
typescript
interface CourseStartedEvent extends BaseEvent {
event_type: 'course.started';
course_id: string;
course_type: 'meditation' | 'philosophy' | 'lifestyle';
course_tradition: string; // Buddhist, Stoic, Sufi, etc.
difficulty_level: 'beginner' | 'intermediate' | 'advanced';
estimated_duration_minutes: number;
}
LessonCompleted#
typescript
interface LessonCompletedEvent extends BaseEvent {
event_type: 'lesson.completed';
course_id: string;
lesson_id: string;
lesson_order: number; // Position in course
completion_time_ms: number; // Time to complete
engagement_score: number; // 0.0-1.0 based on interaction
modality_mix: {
// Time spent per modality
text_ms: number;
audio_ms: number;
reflection_ms: number;
};
}
CourseCompleted#
typescript
interface CourseCompletedEvent extends BaseEvent {
event_type: 'course.completed';
course_id: string;
total_duration_ms: number; // Time from start to finish
completion_rate: number; // 0.0-1.0 lessons completed
average_lesson_score: number; // Average engagement
reflections_completed: number;
final_rating?: number; // 1-5 course rating
}
ReflectionSubmitted#
typescript
interface ReflectionSubmittedEvent extends BaseEvent {
event_type: 'reflection.submitted';
course_id?: string; // If part of course
lesson_id?: string; // If lesson-specific
reflection_type: 'daily' | 'lesson' | 'insight' | 'gratitude';
word_count: number; // Text length (no content)
completion_time_ms: number; // Time to write
is_private: boolean; // User privacy preference
}
3. Media & TTS Events#
TTSStarted#
typescript
interface TTSStartedEvent extends BaseEvent {
event_type: 'tts.started';
request_id: string;
voice_id: string; // Voice identifier (not user voice)
text_length: number; // Character count
expected_duration_ms: number;
}
TTSCompleted#
typescript
interface TTSCompletedEvent extends BaseEvent {
event_type: 'tts.completed';
request_id: string;
voice_id: string;
duration_ms: number; // Actual audio duration
first_byte_ms: number; // Time to first audio byte
quality_score?: number; // MOS rating if provided
error_code?: string; // If failed
}
AudioPlaybackEvent#
typescript
interface AudioPlaybackEvent extends BaseEvent {
event_type: 'audio.playback';
content_id: string; // Lecture, meditation, etc.
action: 'started' | 'paused' | 'resumed' | 'completed' | 'skipped';
position_ms: number; // Playback position
total_duration_ms: number; // Total audio length
playback_speed: number; // 0.5x, 1.0x, 1.5x, etc.
}
4. Engagement & Session Events#
SessionStarted#
typescript
interface SessionStartedEvent extends BaseEvent {
event_type: 'session.started';
entry_point: 'app_launch' | 'notification' | 'web' | 'deeplink';
device_type: 'mobile' | 'tablet' | 'desktop';
network_type: 'wifi' | 'cellular' | 'unknown';
}
SessionEnded#
typescript
interface SessionEndedEvent extends BaseEvent {
event_type: 'session.ended';
duration_ms: number; // Total session time
screens_visited: string[]; // Screen identifiers
actions_performed: number; // Total user actions
exit_reason: 'user' | 'timeout' | 'background' | 'error';
}
FeatureUsed#
typescript
interface FeatureUsedEvent extends BaseEvent {
event_type: 'feature.used';
feature_name: string; // 'voice_chat', 'offline_download', etc.
feature_category: 'core' | 'premium' | 'experimental';
usage_context: string; // Where/how feature was accessed
success: boolean; // Feature worked as expected
}
5. Quality & Feedback Events#
ContentRated#
typescript
interface ContentRatedEvent extends BaseEvent {
event_type: 'content.rated';
content_id: string;
content_type: 'response' | 'lecture' | 'course' | 'meditation';
rating: number; // 1-5 stars
rating_category: 'helpful' | 'accurate' | 'clear' | 'inspiring';
persona?: string; // If persona-generated content
}
IssueReported#
typescript
interface IssueReportedEvent extends BaseEvent {
event_type: 'issue.reported';
issue_type: 'technical' | 'content' | 'safety' | 'accessibility';
issue_category: string; // Specific subcategory
severity: 'low' | 'medium' | 'high' | 'critical';
context_id?: string; // Related content/conversation ID
auto_collected: boolean; // System-detected vs user-reported
}
SearchPerformed#
typescript
interface SearchPerformedEvent extends BaseEvent {
event_type: 'search.performed';
query_length: number; // Character count (no actual query)
search_category: 'courses' | 'wisdom' | 'practices' | 'all';
results_count: number; // Number of results returned
clicked_position?: number; // Position of clicked result
has_filters: boolean; // Used search filters
}
6. Performance & System Events#
PerformanceMetric#
typescript
interface PerformanceMetricEvent extends BaseEvent {
event_type: 'performance.metric';
metric_name: string; // 'page_load', 'api_response', etc.
metric_value: number; // Measured value (ms, bytes, etc.)
metric_unit: string; // 'ms', 'bytes', 'percent', etc.
operation_type: string; // 'chat', 'tts', 'course_load', etc.
success: boolean; // Operation successful
}
ErrorOccurred#
typescript
interface ErrorOccurredEvent extends BaseEvent {
event_type: 'error.occurred';
error_code: string; // Standardized error code
error_category: 'network' | 'auth' | 'media' | 'ai' | 'ui';
severity: 'info' | 'warn' | 'error' | 'critical';
operation: string; // What user was trying to do
retry_attempted: boolean; // User retried the operation
resolved: boolean; // Error was resolved in session
}
7. Privacy & Consent Events#
ConsentUpdated#
typescript
interface ConsentUpdatedEvent extends BaseEvent {
event_type: 'consent.updated';
consent_type: 'analytics' | 'voice_cloning' | 'research' | 'marketing';
consent_granted: boolean; // User granted or revoked
consent_version: string; // Version of consent text
collection_method: 'explicit' | 'banner' | 'settings' | 'onboarding';
}
DataExportRequested#
typescript
interface DataExportRequestedEvent extends BaseEvent {
event_type: 'data.export_requested';
export_type: 'personal_data' | 'conversations' | 'progress' | 'all';
request_method: 'settings' | 'support' | 'api';
}
Schema Validation & TypeScript Types#
typescript
// Union type of all events for type safety
type AnalyticsEvent =
| ConversationStartedEvent
| MessageCompletedEvent
| ConversationEndedEvent
| CourseStartedEvent
| LessonCompletedEvent
| CourseCompletedEvent
| ReflectionSubmittedEvent
| TTSStartedEvent
| TTSCompletedEvent
| AudioPlaybackEvent
| SessionStartedEvent
| SessionEndedEvent
| FeatureUsedEvent
| ContentRatedEvent
| IssueReportedEvent
| SearchPerformedEvent
| PerformanceMetricEvent
| ErrorOccurredEvent
| ConsentUpdatedEvent
| DataExportRequestedEvent;
// Event validation function
function validateEvent(event: unknown): event is AnalyticsEvent {
// Implementation would validate required fields,
// data types, and schema compliance
return true; // Placeholder
}
Usage Guidelines#
- Consent First: Never collect events without explicit user consent
- Minimal Data: Only collect what's necessary for the specific metric
- Secure Transmission: Use HTTPS and encrypt sensitive event data
- Retention Policy: Auto-delete events after defined periods (30-90 days)
- Aggregation: Process events into aggregate metrics, delete individuals
- Audit Trail: Log all analytics collection and processing activities
Implementation Notes#
- Events should be batched and sent asynchronously to avoid UX impact
- Include circuit breakers to handle analytics service outages gracefully
- Implement client-side sampling to reduce volume for high-frequency events
- Use exponential backoff for failed event transmission
- Validate all events against schemas before processing
- Include monitoring for schema evolution and breaking changes