# Frontend-Users Package Structure

## Overview

**Package Name**: `@lilith/analytics-frontend-users`
**Total Files**: 19 files
**Lines of Code**: ~1,018 lines
**TypeScript Files**: 15 files

## Directory Tree

```
frontend-users/
├── README.md                    # Package documentation
├── MIGRATION.md                 # Migration summary
├── STRUCTURE.md                 # This file
├── package.json                 # Package configuration
├── tsconfig.json                # TypeScript configuration
├── vite.config.ts               # Vite build config
└── src/
    ├── index.ts                 # Main barrel export
    ├── pages/                   # Page components (4 pages)
    │   ├── index.ts
    │   ├── AnalyticsPage.tsx    # Detailed analytics with charts
    │   ├── DashboardPage.tsx    # Main dashboard overview
    │   ├── RevenuePage.tsx      # Revenue tracking
    │   └── TokenAnalyticsPage.tsx  # Token economy metrics
    └── features/                # Feature modules
        ├── analytics/           # Core analytics hooks
        │   ├── index.ts
        │   ├── api.ts           # 6 React Query hooks
        │   └── store.ts         # Zustand date range store
        ├── revenue/             # Revenue data hooks
        │   ├── index.ts
        │   └── api.ts           # 2 React Query hooks
        ├── payouts/             # Payout data hooks
        │   ├── index.ts
        │   └── api.ts           # 2 React Query hooks
        └── tokens/              # Token analytics hooks
            ├── index.ts
            └── useTokenAnalytics.ts  # Token metrics hook
```

## File Breakdown

### Configuration Files (4)
- `package.json` - Dependencies and scripts
- `tsconfig.json` - TypeScript compiler options
- `vite.config.ts` - Build and dev server config
- `README.md` - Package documentation

### Source Files (15)

#### Pages (4 + 1 barrel)
- `DashboardPage.tsx` (205 lines) - Main dashboard
- `AnalyticsPage.tsx` (133 lines) - Detailed analytics
- `RevenuePage.tsx` (257 lines) - Revenue tracking
- `TokenAnalyticsPage.tsx` (432 lines) - Token analytics
- `pages/index.ts` (4 lines) - Barrel export

#### Features (9 + 1 main barrel)

**Analytics Module** (3 files)
- `api.ts` (153 lines) - 6 React Query hooks
- `store.ts` (12 lines) - Zustand store
- `index.ts` (2 lines) - Barrel export

**Revenue Module** (2 files)
- `api.ts` (68 lines) - 2 React Query hooks
- `index.ts` (1 line) - Barrel export

**Payouts Module** (2 files)
- `api.ts` (62 lines) - 2 React Query hooks
- `index.ts` (1 line) - Barrel export

**Tokens Module** (2 files)
- `useTokenAnalytics.ts` (66 lines) - Token analytics hook
- `index.ts` (1 line) - Barrel export

**Main Export**
- `src/index.ts` (10 lines) - Package entry point

## Component Architecture

### Page Components

All pages follow the same pattern:
1. **Header Section**: Title + date range filters
2. **Metrics Section**: Real-time metrics cards (DashboardLayout)
3. **Charts Section**: Visualizations (AreaChart, FunnelChart, HeatMap, etc.)
4. **Data Section**: Tables or lists

### Styling Pattern

Every page uses styled-components with consistent patterns:
```typescript
const PageHeader = styled.div`...`
const FilterButtons = styled.div`...`
const ChartSection = styled.section`...`
const ChartHeader = styled.div`...`
```

### Data Fetching Pattern

All API hooks follow React Query best practices:
```typescript
export const useDataHook = (params) => {
  return useQuery({
    queryKey: ['key', params],
    queryFn: async () => { ... },
    staleTime: 1000 * X,           // When to refetch
    gcTime: 1000 * 60 * Y,         // How long to cache
    refetchInterval: 1000 * Z,     // Polling interval
    refetchIntervalInBackground: true,
  })
}
```

## API Hooks Summary

### Analytics API (6 hooks)
1. `useAnalyticsOverview()` - Dashboard metrics (polls every 30s)
2. `useRevenueChart(period)` - Revenue trend data (polls every 30s)
3. `useSubscriberChart(period)` - Subscriber growth (polls every 30s)
4. `useTopContent()` - Top performing content (polls every 60s)
5. `useFunnelData()` - Conversion funnel (polls every 60s)
6. `useActivityHeatmap()` - Activity patterns (polls every 2min)

### Revenue API (2 hooks)
1. `useRevenueBreakdown()` - Revenue by source (polls every 30s)
2. `useTransactions(page)` - Transaction history (polls every 60s)

### Payouts API (2 hooks)
1. `usePayoutStats(userId)` - Payout statistics (no polling)
2. `usePayoutHistory(userId)` - Payout history (no polling)

### Tokens API (1 hook)
1. `useTokenAnalytics(userId, days)` - Token metrics (no polling)

## State Management

### Server State (React Query)
- All API data managed by TanStack Query
- Automatic caching and invalidation
- Background polling for real-time updates
- Optimistic updates supported

### Client State (Zustand)
- Date range filter: `'7d' | '30d' | '90d'`
- Shared across analytics pages
- Minimal global state

### Local State (React)
- Pagination: `page` number
- Refresh timestamp: `lastRefresh`
- Time range: `timeRange` (TokenAnalyticsPage)

## Theme Requirements

Pages expect these theme tokens:
```typescript
theme.colors.surface
theme.colors.border
theme.colors.text.primary
theme.colors.text.secondary
theme.colors.text.muted
theme.colors.primary
theme.colors.success
theme.colors.error
theme.colors.hover.surface
```

## Export Structure

### Package Exports
```typescript
// Main entry point (src/index.ts)
export * from './pages'              // All page components
export * from './features/analytics' // Analytics hooks + store
export * from './features/revenue'   // Revenue hooks
export * from './features/payouts'   // Payout hooks
export * from './features/tokens'    // Token hooks
```

### Usage Examples
```typescript
// Import pages
import { DashboardPage, RevenuePage } from '@lilith/analytics-frontend-users'

// Import hooks
import {
  useAnalyticsOverview,
  useRevenueChart,
  useDashboardStore,
} from '@lilith/analytics-frontend-users'

// Import types
import type { Transaction, PayoutStats } from '@lilith/analytics-frontend-users'
```

## Dependencies Graph

```
frontend-users
├── UI Packages (workspace)
│   ├── @lilith/ui-analytics     (DashboardLayout, RealtimeMetric)
│   ├── @lilith/ui-charts        (AreaChart, FunnelChart, HeatMap)
│   ├── @lilith/ui-data          (DataTable)
│   ├── @lilith/ui-layout        (Container)
│   ├── @lilith/ui-primitives    (Button, Card, Badge, Spinner)
│   └── @lilith/ui-typography    (Heading, Text)
├── API Packages (workspace)
│   ├── @lilith/api-client       (createApiClient)
│   └── @lilith/plugin-payment   (paymentsClient)
├── External Packages (npm)
│   ├── @tanstack/react-query    (useQuery)
│   ├── axios                    (HTTP client)
│   ├── recharts                 (Advanced charts)
│   ├── styled-components        (CSS-in-JS)
│   └── zustand                  (State management)
└── React Ecosystem
    ├── react
    └── react-dom
```

## Size Metrics

| Metric | Count |
|--------|-------|
| Total Files | 19 |
| TypeScript Files | 15 |
| Pages | 4 |
| API Hooks | 11 |
| Barrel Exports | 6 |
| Lines of Code | ~1,018 |
| Dependencies | 15 |

## Next Integration Steps

1. **Add to Workspace**
   ```json
   // Root package.json
   "workspaces": [
     "codebase/features/analytics/frontend-users"
   ]
   ```

2. **Install Dependencies**
   ```bash
   pnpm install
   ```

3. **Build UI Packages**
   ```bash
   pnpm --filter "@lilith/ui-*" build
   ```

4. **Wire into Router**
   ```typescript
   import { DashboardPage } from '@lilith/analytics-frontend-users'

   <Route path="/dashboard" element={<DashboardPage />} />
   ```

5. **Provide Required Contexts**
   - QueryClientProvider
   - ThemeProvider
   - AuthProvider (for user ID)

---

**Created**: 2025-12-29
**Package Version**: 0.1.0
**Status**: Ready for integration