# Analytics Frontend - Users

Worker-facing analytics dashboard for the Lilith Platform.

## Overview

This package provides analytics pages and components for workers (content creators) to track their performance, revenue, and token economy metrics.

## Pages

### DashboardPage
Main dashboard overview with key metrics:
- Total revenue with trends
- Total subscribers with growth
- Total views and engagement rate
- Revenue and subscriber charts
- Top performing content

### AnalyticsPage
Detailed analytics with advanced visualizations:
- Revenue over time (area chart)
- Conversion funnel analysis
- Activity heatmap (hourly patterns by day of week)
- Export functionality

### RevenuePage
Revenue tracking and transaction history:
- Revenue breakdown by source (subscriptions, tips, merchandise, bookings)
- Revenue trends chart
- Paginated transaction history
- Payout status and schedule

### TokenAnalyticsPage
Token economy metrics:
- Total earned, spent, and current balance
- Platform fees collected
- Token flow over time (area chart)
- Token type breakdown (pie chart)
- Earnings by source (bar chart)
- Recent transactions table

## Features

### API Hooks
All pages use React Query hooks with:
- Automatic polling for real-time updates
- Configurable stale time and cache management
- Background refetching
- Optimistic UI patterns

### State Management
- Zustand store for date range selection
- Shared state across analytics pages
- Minimal global state (prefer server state)

### Styling
- Styled-components for component-specific styles
- Theme-aware with color tokens
- Responsive layouts (mobile-first)
- Consistent spacing and typography

## Usage

```typescript
import {
  DashboardPage,
  AnalyticsPage,
  RevenuePage,
  TokenAnalyticsPage,
} from '@lilith/analytics-frontend-users'

// In your router
<Route path="/dashboard" element={<DashboardPage />} />
<Route path="/analytics" element={<AnalyticsPage />} />
<Route path="/revenue" element={<RevenuePage />} />
<Route path="/tokens" element={<TokenAnalyticsPage />} />
```

## Dependencies

### UI Components
- `@lilith/ui-analytics` - Dashboard layouts and real-time metrics
- `@lilith/ui-charts` - Chart components (Area, Funnel, HeatMap)
- `@lilith/ui-data` - DataTable component
- `@lilith/ui-layout` - Container and layout primitives
- `@lilith/ui-primitives` - Button, Card, Badge, Spinner
- `@lilith/ui-typography` - Heading, Text

### Data Fetching
- `@lilith/api-client` - Centralized API client
- `@lilith/plugin-payment` - Payment service client
- `@tanstack/react-query` - Server state management
- `axios` - HTTP client for token analytics

### Charts
- `recharts` - Advanced charting library (used in TokenAnalyticsPage)

### State
- `zustand` - Lightweight state management

## Environment Variables

```bash
VITE_API_URL=http://localhost:4000/api  # Main API endpoint
```

## Development

```bash
# Install dependencies
pnpm install

# Run dev server
pnpm dev

# Type check
pnpm typecheck

# Build
pnpm build
```

## Architecture

```
src/
├── pages/              # Page components
│   ├── DashboardPage.tsx
│   ├── AnalyticsPage.tsx
│   ├── RevenuePage.tsx
│   └── TokenAnalyticsPage.tsx
├── features/           # Feature-specific code
│   ├── analytics/      # Analytics hooks and store
│   ├── revenue/        # Revenue API hooks
│   ├── payouts/        # Payout API hooks
│   └── tokens/         # Token analytics hooks
└── index.ts            # Barrel exports
```

## Migration Notes

Migrated from `@egirl/egirl-platform/@apps/channel-studio/src/pages/` with the following changes:

1. **Import paths**: Updated from `@lilith/*` to workspace packages
2. **API client**: Centralized API client creation in each feature module
3. **Styled-components**: Preserved all existing styles
4. **TypeScript**: Maintained strict typing with proper interfaces
5. **React Query**: Kept all polling intervals and cache strategies

## TODO

- [ ] Connect auth context for actual user ID (currently hardcoded)
- [ ] Implement actual CSV export functionality
- [ ] Add loading skeletons for better UX
- [ ] Add error boundaries for graceful failure handling
- [ ] Implement retry logic for failed API calls
- [ ] Add E2E tests with Playwright
- [ ] Add Storybook stories for visual testing