Create ANALYTICS.md

ANALYTICS.md

@@ -0,0 +1,329 @@
+# Analytics System Documentation
+
+## Overview
+
+The analytics system provides comprehensive insights into store performance, sales trends, customer behavior, and order management. It supports both vendors and staff users (sub-users) with appropriate access controls and server-side rendering for optimal performance.
+
+## Features
+
+### 🔐 Multi-User Support
+- **Vendors**: Access their own store analytics automatically
+- **Staff/Sub-Users**: Access store analytics by providing a `storeId` parameter via URL or cookies
+- **Role-based Access**: Different permissions for different user types
+- **Server-side Rendering**: Initial data fetched server-side for better performance
+
+### 📊 Analytics Dashboard
+- **Overview Metrics**: Total revenue, orders, customers, and products
+- **Revenue Trends**: Time-based revenue analysis with interactive charts
+- **Product Performance**: Top-selling products with stock status
+- **Customer Insights**: Customer segmentation and behavior analysis
+- **Order Analytics**: Order status distribution and processing times
+
+### 🎯 Key Metrics
+- Total and monthly revenue
+- Order completion rates
+- Customer acquisition and retention
+- Product performance rankings
+- Average order processing times
+
+## API Endpoints
+
+### Authentication
+All endpoints require authentication using the new `protectStore` middleware:
+
+```javascript
+// For vendors (automatic store access)
+GET /api/analytics/overview
+
+// For staff users (requires storeId parameter)
+GET /api/analytics/overview?storeId=store_id_here
+```
+
+### Available Endpoints
+
+#### 1. Analytics Overview
+```http
+GET /api/analytics/overview
+```
+Returns comprehensive overview metrics including:
+- Order statistics (total, completed, pending, completion rate)
+- Revenue data (total, monthly, weekly, average order value)
+- Product count
+- Unique customer count
+- User type (vendor/staff)
+
+#### 2. Revenue Trends
+```http
+GET /api/analytics/revenue-trends?period=30&storeId=optional
+```
+Returns daily revenue and order trends for the specified period.
+
+#### 3. Product Performance
+```http
+GET /api/analytics/product-performance?storeId=optional
+```
+Returns top-performing products with sales metrics and stock status.
+
+#### 4. Customer Insights
+```http
+GET /api/analytics/customer-insights?storeId=optional
+```
+Returns customer segmentation and top customer analysis.
+
+#### 5. Order Analytics
+```http
+GET /api/analytics/order-analytics?period=30&storeId=optional
+```
+Returns order status distribution and processing time analysis.
+
+## Frontend Implementation
+
+### Server-Side Rendering
+The analytics page uses server-side rendering for optimal performance:
+
+```typescript
+// app/dashboard/analytics/page.tsx
+export default async function AnalyticsPage({
+  searchParams,
+}: {
+  searchParams: { storeId?: string };
+}) {
+  const storeId = searchParams.storeId;
+  const initialData = await getAnalyticsOverviewServer(storeId);
+  
+  return <AnalyticsDashboard initialData={initialData} />;
+}
+```
+
+### Store Selection for Staff Users
+Staff users can select which store to view analytics for:
+
+```typescript
+// URL-based store selection
+/dashboard/analytics?storeId=store_id_here
+
+// StoreSelector component for easy store switching
+<StoreSelector />
+```
+
+### Components
+
+#### AnalyticsDashboard
+Main dashboard component with tabs for different analytics views.
+
+**Props:**
+- `initialData`: Initial analytics overview data (server-side fetched)
+
+**Features:**
+- Key metrics cards with trend indicators
+- Tabbed interface for different analytics views
+- Refresh functionality
+- User type indicator (Vendor/Staff View)
+
+#### StoreSelector
+Client-side component for staff users to select stores.
+
+**Features:**
+- Input field for store ID
+- URL-based navigation
+- Current store display
+- Error handling and validation
+
+#### RevenueChart
+Displays revenue trends over time with interactive charts.
+
+**Props:**
+- `timeRange`: Time period for analysis (7, 30, 90 days)
+
+#### ProductPerformanceChart
+Shows top-performing products in a table format.
+
+#### CustomerInsightsChart
+Displays customer segmentation and top customers.
+
+#### OrderAnalyticsChart
+Shows order status distribution and daily trends.
+
+**Props:**
+- `timeRange`: Time period for analysis
+
+#### MetricsCard
+Reusable component for displaying individual metrics.
+
+**Props:**
+- `title`: Metric title
+- `value`: Metric value
+- `description`: Metric description
+- `icon`: Lucide icon component
+- `trend`: Trend direction ("up", "down", "neutral")
+- `trendValue`: Trend description
+
+## Sub-User (Staff) Support
+
+### Authentication Flow
+1. Staff users authenticate using their staff credentials
+2. When accessing analytics, they must provide a `storeId` parameter
+3. The system verifies the store exists and grants access
+4. All analytics data is filtered by the specified store
+
+### Access Methods
+Staff users can access store analytics in multiple ways:
+
+1. **URL Parameter**: `/dashboard/analytics?storeId=store_id_here`
+2. **Store Selector**: Use the StoreSelector component to choose a store
+3. **Cookies**: Store ID can be stored in cookies for persistence
+
+### Frontend Integration
+The analytics service automatically handles both user types:
+
+```typescript
+// Server-side (for initial load)
+const data = await getAnalyticsOverviewServer(storeId);
+
+// Client-side (for refreshes and updates)
+const data = await getAnalyticsOverviewWithStore();
+```
+
+## Usage Examples
+
+### Basic Analytics Access
+```typescript
+// Server-side rendering
+import { getAnalyticsOverviewServer } from '@/lib/server-api';
+const overview = await getAnalyticsOverviewServer(storeId);
+
+// Client-side updates
+import { getAnalyticsOverviewWithStore } from '@/lib/services/analytics-service';
+const overview = await getAnalyticsOverviewWithStore();
+```
+
+### Staff User with Specific Store
+```typescript
+// Navigate to analytics with store ID
+router.push(`/dashboard/analytics?storeId=${storeId}`);
+
+// Or use the store selector component
+<StoreSelector />
+```
+
+### Revenue Trends with Time Range
+```typescript
+import { getRevenueTrendsWithStore } from '@/lib/services/analytics-service';
+
+// Get 30-day revenue trends
+const trends = await getRevenueTrendsWithStore('30');
+```
+
+## Data Structure
+
+### AnalyticsOverview
+```typescript
+interface AnalyticsOverview {
+  orders: {
+    total: number;
+    completed: number;
+    pending: number;
+    completionRate: string;
+  };
+  revenue: {
+    total: number;
+    monthly: number;
+    weekly: number;
+    averageOrderValue: number;
+  };
+  products: {
+    total: number;
+  };
+  customers: {
+    unique: number;
+  };
+  userType?: 'vendor' | 'staff';
+}
+```
+
+### RevenueData
+```typescript
+interface RevenueData {
+  _id: {
+    year: number;
+    month: number;
+    day: number;
+  };
+  revenue: number;
+  orders: number;
+}
+```
+
+### ProductPerformance
+```typescript
+interface ProductPerformance {
+  productId: string;
+  name: string;
+  image: string;
+  unitType: string;
+  currentStock: number;
+  stockStatus: string;
+  totalSold: number;
+  totalRevenue: number;
+  orderCount: number;
+  averagePrice: number;
+}
+```
+
+## Security Considerations
+
+### Access Control
+- Vendors can only access their own store data
+- Staff users must provide valid storeId parameter
+- All requests are authenticated and authorized
+- Store ownership is verified for staff access
+
+### Data Privacy
+- Customer data is anonymized in analytics
+- No sensitive information is exposed
+- All data is filtered by store ownership
+
+## Error Handling
+
+The system provides comprehensive error handling:
+
+- **401 Unauthorized**: Invalid or missing authentication → Redirect to login
+- **400 Bad Request**: Missing storeId for staff users → Show store selector
+- **403 Forbidden**: Access denied to specific store
+- **404 Not Found**: Store not found
+- **500 Server Error**: Internal server errors
+
+All errors are displayed to users via toast notifications in the frontend.
+
+## Performance Optimization
+
+- **Server-side data fetching** for initial load
+- **Client-side caching** for subsequent requests
+- **Efficient database queries** with proper indexing
+- **Pagination** for large datasets
+- **Real-time data refresh** capabilities
+- **Optimized rendering** with React Suspense
+
+## Backend Implementation
+
+### Middleware
+- `protectStore`: Handles both vendors and staff users
+- `protectVendorOnly`: Vendor-specific routes
+- `protectStaffOnly`: Staff-specific routes
+
+### Database Queries
+- Uses `storeId` for consistent data filtering
+- Aggregation pipelines for complex analytics
+- Proper indexing for performance
+- Time-based filtering for trends
+
+## Future Enhancements
+
+- Real-time analytics updates
+- Export functionality for reports
+- Advanced filtering and date range selection
+- Custom dashboard configurations
+- Email reports and notifications
+- Comparative analytics (period-over-period)
+- Predictive analytics and forecasting
+- Multi-store comparison for staff users