274 lines
8 KiB
Markdown
Executable file
274 lines
8 KiB
Markdown
Executable file
# 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
|