platform-codebase/features/analytics/frontend-users/STRUCTURE.md

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:

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:

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:

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

// 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

// 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

   // Root package.json
   "workspaces": [
     "codebase/features/analytics/frontend-users"
   ]
   

2. Install Dependencies

   pnpm install
   

3. Build UI Packages

   pnpm --filter "@lilith/ui-*" build
   

4. Wire into Router

   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