# RateRight Metrics Dashboard Specification

## Overview
This document outlines the technical specification for the RateRight metrics dashboard, designed to track key business metrics across the AARRR (Acquisition, Activation, Retention, Revenue, Referral) framework.

## 1. Key Metrics to Track

### 1.1 Acquisition Metrics
- **Website Visitors**: Total unique visitors to RateRight website
- **Traffic Sources**: Breakdown by organic, paid, referral, direct
- **Landing Page Conversion Rate**: % of visitors who sign up
- **Cost Per Acquisition (CPA)**: Total marketing spend / new signups
- **Signup Conversion Funnel**: Step-by-step conversion rates

### 1.2 Activation Metrics
- **Trial Signups**: Number of users starting free trial
- **Profile Completion Rate**: % of users completing profile setup
- **First Quote Request**: % of trial users requesting first quote
- **First Quote Delivered**: % of users receiving first quote
- **Activation Rate**: % of trial users who complete key activation events
- **Time to Activate**: Average days from signup to activation

### 1.3 Retention Metrics
- **Daily Active Users (DAU)**: Users active in last 24 hours
- **Monthly Active Users (MAU)**: Users active in last 30 days
- **DAU/MAU Ratio**: Stickiness metric
- **Churn Rate**: % of users who cancel subscription monthly
- **Cohort Retention**: Retention curves by signup month
- **User Engagement Score**: Composite metric based on activity

### 1.4 Revenue Metrics
- **Monthly Recurring Revenue (MRR)**: Total monthly subscription revenue
- **Average Revenue Per User (ARPU)**: MRR / total active users
- **Customer Lifetime Value (CLV)**: Predicted revenue per customer
- **Revenue Churn**: MRR lost from cancellations
- **Expansion Revenue**: Additional revenue from existing customers
- **Revenue Growth Rate**: Month-over-month MRR growth

### 1.5 Referral Metrics
- **Net Promoter Score (NPS)**: Customer satisfaction metric
- **Referral Rate**: % of users who refer others
- **Referral Conversion Rate**: % of referrals that convert
- **Viral Coefficient**: Average number of invites per user
- **Customer Acquisition Cost (CAC) Payback**: Months to recover CAC

## 2. Dashboard Layout and Visualizations

### 2.1 Executive Summary Dashboard
**Layout**: Single-page overview with key KPIs
**Visualizations**:
- KPI cards showing current value, change %, and trend indicator
- Line chart for MRR growth over time
- Funnel visualization for AARRR metrics
- Gauge chart for NPS score
- Bar chart comparing current vs target metrics

### 2.2 Detailed Analytics Dashboard
**Layout**: Tabbed interface by metric category
**Tabs and Visualizations**:

#### Acquisition Tab
- Traffic sources pie chart
- Conversion funnel with drop-off rates
- Geographic heat map of signups
- Time series of daily signups

#### Activation Tab
- Activation rate by cohort
- Time to activate distribution
- Feature adoption matrix
- Onboarding completion flow

#### Retention Tab
- Cohort retention curves
- DAU/MAU trend lines
- Churn prediction scatter plot
- User engagement heatmap

#### Revenue Tab
- MRR growth chart
- Revenue breakdown by plan type
- CLV distribution histogram
- Expansion vs churn waterfall

#### Referral Tab
- NPS trend over time
- Referral source analysis
- Viral coefficient tracking
- Customer satisfaction distribution

### 2.3 Real-time Operations Dashboard
**Layout**: Live updating metrics with 5-minute refresh
**Visualizations**:
- Live user activity map
- Real-time signup counter
- System performance metrics
- Alert status indicators

## 3. Data Sources and Calculation Methods

### 3.1 Data Sources

#### Primary Sources
- **Supabase Database**: User data, subscriptions, activities
- **Google Analytics**: Website traffic and conversion data
- **Stripe**: Payment and subscription data
- **Segment**: User event tracking
- **Intercom**: Customer support and engagement data

#### Secondary Sources
- **Email Marketing Platform**: Campaign performance
- **Social Media APIs**: Social engagement metrics
- **CRM System**: Sales pipeline data
- **Customer Feedback Tools**: NPS and satisfaction scores

### 3.2 Data Collection Methods

#### Event Tracking
```javascript
// Example event structure
{
  "event": "user_signup",
  "user_id": "usr_123",
  "timestamp": "2026-02-12T10:30:00Z",
  "properties": {
    "source": "google_ads",
    "campaign": "summer_2026",
    "landing_page": "/pricing"
  }
}
```

#### Database Queries
```sql
-- MRR Calculation
SELECT 
  DATE_TRUNC('month', created_at) as month,
  SUM(amount) as mrr
FROM subscriptions
WHERE status = 'active'
GROUP BY month
ORDER BY month;

-- Cohort Retention
SELECT 
  DATE_TRUNC('month', signup_date) as cohort_month,
  months_since_signup,
  COUNT(DISTINCT user_id) as retained_users
FROM user_activity
GROUP BY cohort_month, months_since_signup;
```

### 3.3 Data Processing Pipeline
1. **Raw Data Collection**: Events and database changes
2. **ETL Process**: Extract, Transform, Load to data warehouse
3. **Data Modeling**: Create dimensional models for analysis
4. **Aggregation**: Pre-compute common metrics
5. **Caching**: Store frequently accessed data
6. **API Layer**: Serve data to dashboard

### 3.4 Metric Calculation Formulas

#### Churn Rate
```
Churn Rate = (Customers Lost in Period) / (Customers at Start of Period) × 100
```

#### CLV (Simplified)
```
CLV = ARPU × Gross Margin % × Customer Lifespan (months)
```

#### NPS
```
NPS = % Promoters (9-10) - % Detractors (0-6)
```

#### Viral Coefficient
```
Viral Coefficient = (Number of Invites Sent × Conversion Rate) / Total Users
```

## 4. Alert Thresholds for Anomalies

### 4.1 Critical Alerts (Immediate Notification)
| Metric | Threshold | Notification Method |
|--------|-----------|-------------------|
| Website Downtime | > 5 minutes | SMS, Email, Slack |
| Payment Processing Failure | > 1% failure rate | SMS, Email |
| Signup Drop | > 30% below 7-day average | Email, Slack |
| Churn Spike | > 5% daily churn rate | Email, Slack |

### 4.2 Warning Alerts (Daily Digest)
| Metric | Threshold | Notification Method |
|--------|-----------|-------------------|
| MRR Growth | < 5% month-over-month | Email |
| Activation Rate | < 20% for 3 consecutive days | Email |
| Support Ticket Volume | > 50% increase vs last week | Email |
| NPS Score | < 30 | Email |

### 4.3 Anomaly Detection
- **Statistical Method**: 3-sigma rule for normally distributed metrics
- **Machine Learning**: Prophet for time series forecasting
- **Comparative Analysis**: Year-over-year and month-over-month comparisons
- **Cohort Analysis**: Identify cohort-specific issues

### 4.4 Alert Configuration
```yaml
alerts:
  - name: "Low Activation Rate"
    metric: "activation_rate"
    condition: "< 0.20"
    duration: "3d"
    severity: "warning"
    channels: ["email", "slack"]
    
  - name: "High Churn Rate"
    metric: "churn_rate"
    condition: "> 0.05"
    duration: "1d"
    severity: "critical"
    channels: ["sms", "email", "slack"]
```

## 5. Technical Implementation

### 5.1 Technology Stack
- **Frontend**: React with D3.js for visualizations
- **Backend**: Node.js/Express API
- **Database**: PostgreSQL with TimescaleDB extension
- **Cache**: Redis for real-time data
- **Queue**: Redis/RabbitMQ for async processing
- **Monitoring**: Grafana for infrastructure metrics

### 5.2 API Endpoints
```
GET /api/v1/metrics/executive-summary
GET /api/v1/metrics/acquisition
GET /api/v1/metrics/activation
GET /api/v1/metrics/retention
GET /api/v1/metrics/revenue
GET /api/v1/metrics/referral
GET /api/v1/alerts
POST /api/v1/alerts/configure
```

### 5.3 Security Considerations
- Role-based access control (RBAC)
- API rate limiting
- Data encryption in transit and at rest
- Audit logging for all data access
- GDPR compliance for user data

## 6. Maintenance and Updates

### 6.1 Regular Maintenance
- Daily: Verify data pipeline integrity
- Weekly: Review alert thresholds
- Monthly: Update metric definitions based on business changes
- Quarterly: Full dashboard performance review

### 6.2 Version Control
- All dashboard changes tracked in Git
- A/B testing for major UI changes
- Rollback procedures documented
- Change log maintained

## 7. Success Criteria

### 7.1 Dashboard Adoption
- 80% of executive team checks dashboard daily
- 90% of decisions backed by dashboard data
- <5 second load time for all visualizations

### 7.2 Business Impact
- 20% improvement in decision-making speed
- 15% reduction in customer churn
- 25% increase in activation rate
- 10% improvement in forecasting accuracy

---

*Document Version: 1.0*
*Created: 2026-02-12*
*Next Review: 2026-05-12*