platform-codebase/@packages/@plugins/analytics/MOCK_DATA_QUICKSTART.md

# Analytics Mock Data - Quick Start

## TL;DR

Enable mock analytics data without a backend:

```bash
# Add to .env.local
VITE_MOCK_ANALYTICS=true
```

```tsx
// Use mockable hooks instead of regular ones
import { useRevenueMetrics } from '@lilith/analytics/hooks/useAdminQueryMockable';
```

Done! Your analytics pages now work without a backend.

---

## 3 Ways to Use Mock Data

### 1. Environment Variable (Best for Development)

```bash
# .env.local or .env.development
VITE_MOCK_ANALYTICS=true
```

```tsx
import { useRevenueMetrics } from '@lilith/analytics/hooks/useAdminQueryMockable';

function Revenue() {
  const { data } = useRevenueMetrics(); // Auto-uses mock data
}
```

### 2. Provider Wrapper (Best for Testing/Storybook)

```tsx
import { MockDataProvider } from '@lilith/analytics/providers';

<MockDataProvider enabled={true}>
  <YourComponent />
</MockDataProvider>
```

### 3. Direct Access (Best for Unit Tests)

```tsx
import { mockData } from '@lilith/analytics/providers';

const revenue = mockData.revenueMetrics;
const transactions = mockData.transactions();
```

---

## Available Mock Data

All 26 analytics hooks have realistic mock data:

| Category | Hooks | Data Included |
|----------|-------|---------------|
| **Revenue** | 3 | Metrics, trend (30d), breakdown by source/provider |
| **Transactions** | 2 | 50 transactions, detailed transaction view |
| **P&L** | 3 | Statement, trend (12mo), reserve progress |
| **Real-Time** | 3 | Live metrics, activity stream, active users chart |
| **Costs** | 3 | Metrics, breakdown, budget comparison |
| **Performance** | 2 | Response times, per-endpoint metrics |
| **Errors** | 3 | Metrics, by type, recent errors list |
| **Bounce Rate** | 2 | Overall metrics, per-page breakdown |
| **Conversions** | 3 | Metrics, funnel data, by source |
| **A/B Testing** | 2 | Test metrics, active tests list |

---

## Migration Guide

### Update Page Imports

**Before:**
```tsx
import {
  useRevenueMetrics,
  useRevenueTrend,
} from '../hooks/useAdminQuery';
```

**After:**
```tsx
import {
  useRevenueMetrics,
  useRevenueTrend,
} from '../hooks/useAdminQueryMockable';
```

No other changes needed! Same API, same types.

---

## Sample Mock Data

### Revenue Metrics
```json
{
  "totalRevenue": 487250.34,
  "monthlyRecurring": 324180.00,
  "cryptoRevenue": 89420.50,
  "growthRate": 23.4,
  "avgRevenuePerUser": 48.72
}
```

### Real-Time Metrics
```json
{
  "activeUsers": 127,
  "activeCreators": 34,
  "liveTransactions": 12,
  "revenuePerMinute": 142.50,
  "systemLoad": 0.68,
  "responseTime": 87
}
```

### Transaction
```json
{
  "id": "txn_1001",
  "type": "subscription",
  "status": "completed",
  "amount": 250.00,
  "provider": "Stripe",
  "timestamp": "2025-12-26T10:30:00Z"
}
```

---

## Demo

Interactive demo showing all mock data:

```tsx
import { MockDataProviderDemo } from '@lilith/analytics/providers/MockDataProvider.demo';

function App() {
  return <MockDataProviderDemo />;
}
```

---

## Examples

See `src/providers/MockDataProvider.example.tsx` for:
- ✅ App-level provider wrapping
- ✅ Conditional mock (dev vs prod)
- ✅ Runtime toggle
- ✅ Storybook integration
- ✅ Testing setup
- ✅ Direct data access

---

## Files

| File | Purpose |
|------|---------|
| `MockDataProvider.tsx` | Core implementation (600 lines) |
| `useMockableQuery.ts` | Hook wrapper utilities |
| `useAdminQueryMockable.ts` | Mockable versions of all hooks |
| `MockDataProvider.README.md` | Full documentation |
| `MockDataProvider.example.tsx` | Usage examples |
| `MockDataProvider.demo.tsx` | Interactive demo |

---

## Troubleshooting

**Mock data not loading?**
- Check `VITE_MOCK_ANALYTICS="true"` (string, not boolean)
- Verify using hooks from `useAdminQueryMockable`
- Ensure component wrapped in `<MockDataProvider>`

**TypeScript errors?**
- Mock data matches all types from `useAdminQuery.ts`
- Update mock data if you change API interfaces

**Still fetching real data?**
- Clear cache and restart dev server
- Check environment variable is being read
- Verify `enabled` prop is `true` on provider

---

## Next Steps

1. Add `VITE_MOCK_ANALYTICS=true` to `.env.local`
2. Update page imports to use mockable hooks
3. Start dev server and test pages
4. When backend ready, remove env var or set to `false`

---

**Full docs**: `src/providers/MockDataProvider.README.md`