# Business KPI Definitions & Calculations

## Overview

Lilith tracks comprehensive business metrics across user engagement, conversion, revenue, content, and technical performance. All KPIs are calculated from real-time analytics events and updated continuously.

## User Engagement KPIs

### Daily Active Users (DAU)
- **Definition**: Unique users with session.started events in past 24 hours
- **Calculation**: `COUNT(DISTINCT user_hash) WHERE event_type = "session.started" AND timestamp >= NOW() - INTERVAL 1 DAY`
- **Target**: Growing 15% month-over-month
- **Alert Threshold**: Drop > 10% day-over-day

### Weekly Active Users (WAU)
- **Definition**: Unique users with session.started events in past 7 days
- **Calculation**: `COUNT(DISTINCT user_hash) WHERE event_type = "session.started" AND timestamp >= NOW() - INTERVAL 7 DAY`
- **Target**: Growing 10% month-over-month
- **Alert Threshold**: Drop > 15% week-over-week

### Monthly Active Users (MAU)
- **Definition**: Unique users with session.started events in past 30 days
- **Calculation**: `COUNT(DISTINCT user_hash) WHERE event_type = "session.started" AND timestamp >= NOW() - INTERVAL 30 DAY`
- **Target**: Growing 5% month-over-month
- **Alert Threshold**: Drop > 20% month-over-month

## Conversion KPIs

### 24-Hour Signup Conversion Rate
- **Definition**: Percentage of visitors who complete signup within 24 hours
- **Calculation**: `(COUNT(DISTINCT user_hash WHERE event_type = "signup.completed") / DAU) * 100`
- **Target**: > 2.5%
- **Alert Threshold**: < 1.5%

### Chat Engagement Rate
- **Definition**: Percentage of sessions that include chat interactions
- **Calculation**: `(Sessions with chat.message_sent / Total sessions) * 100`
- **Target**: > 60%
- **Alert Threshold**: < 40%

### Voice Feature Adoption
- **Definition**: Percentage of users using voice features monthly
- **Calculation**: `(MAU with voice.session_started / MAU) * 100`
- **Target**: > 25%
- **Alert Threshold**: < 15%

## Revenue KPIs

### 30-Day Revenue
- **Definition**: Total revenue in USD over past 30 days
- **Calculation**: `SUM(payment.amount_usd) WHERE timestamp >= NOW() - INTERVAL 30 DAY`
- **Target**: Growing 20% month-over-month
- **Alert Threshold**: Drop > 5% month-over-month

### Average Revenue Per User (ARPU)
- **Definition**: Monthly recurring revenue divided by active paying users
- **Calculation**: `Monthly Revenue / COUNT(DISTINCT paying_users)`
- **Target**: > $15/month
- **Alert Threshold**: < $10/month

## Content Engagement KPIs

### Content Engagement Score
- **Definition**: Average session duration and completion rates
- **Calculation**: `AVG(session_duration_minutes) * completion_rate_percentage`
- **Target**: > 15 minutes with >70% completion
- **Alert Threshold**: < 8 minutes or <50% completion

### Meditation Completion Rate
- **Definition**: Percentage of meditation sessions completed
- **Calculation**: `(meditation.completed / meditation.started) * 100`
- **Target**: > 80%
- **Alert Threshold**: < 60%

## Technical Performance KPIs

### API Performance Score
- **Definition**: Composite score of latency, error rate, and throughput
- **Calculation**: `(100 - error_rate_percentage) * latency_score * throughput_score`
- **Target**: > 95
- **Alert Threshold**: < 85

### Service Uptime
- **Definition**: Percentage of time services are available
- **Calculation**: `(Total time - Downtime) / Total time * 100`
- **Target**: > 99.9%
- **Alert Threshold**: < 99.5%

## Data Sources & Event Types

### Analytics Events

| Event Type | Description | KPI Impact |
|------------|-------------|------------|
| `session.started` | User begins session | DAU/WAU/MAU calculation |
| `signup.completed` | User completes registration | Conversion rate |
| `chat.message_sent` | User sends chat message | Chat engagement |
| `voice.session_started` | User starts voice interaction | Voice adoption |
| `meditation.started` | User begins meditation | Content engagement |
| `meditation.completed` | User completes meditation | Completion rate |
| `payment.completed` | User completes payment | Revenue tracking |

### Data Quality Requirements

- **User Identity**: Must use `user_hash` when available, fallback to `session_id`
- **Timestamp**: All events must have valid ISO8601 timestamps
- **Consent**: Only include events from users with analytics consent
- **Deduplication**: Remove duplicate events within 5-minute windows

## KPI Calculation Examples

### Real-time DAU Calculation

```javascript
const calculateDAU = async (analyticsService) => {
  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);

  const query = {
    event_type: 'session.started',
    timestamp: { $gte: oneDayAgo },
    consent: true
  };

  const events = await analyticsService.getEvents(query);
  const uniqueUsers = new Set(
    events.map(event => event.user_hash || event.session_id)
  );

  return uniqueUsers.size;
};
```

### Conversion Rate Calculation

```javascript
const calculateConversionRate = async (analyticsService) => {
  const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);

  // Get DAU
  const dau = await calculateDAU(analyticsService);

  // Get signup completions
  const signupQuery = {
    event_type: 'signup.completed',
    timestamp: { $gte: oneDayAgo },
    consent: true
  };

  const signupEvents = await analyticsService.getEvents(signupQuery);
  const uniqueSignups = new Set(
    signupEvents.map(event => event.user_hash || event.session_id)
  );

  return (uniqueSignups.size / dau) * 100;
};
```

---
*Generated automatically by business-metrics-docs-generator.js*
*Last updated: 2025-09-26T09:29:19.727Z*
