ember-market-frontend/docs/ANALYTICS.md

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:

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

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

GET /api/analytics/revenue-trends?period=30&storeId=optional

Returns daily revenue and order trends for the specified period.

3. Product Performance

GET /api/analytics/product-performance?storeId=optional

Returns top-performing products with sales metrics and stock status.

4. Customer Insights

GET /api/analytics/customer-insights?storeId=optional

Returns customer segmentation and top customer analysis.

5. Order Analytics

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:

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

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

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

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

// Navigate to analytics with store ID
router.push(`/dashboard/analytics?storeId=${storeId}`);

// Or use the store selector component
<StoreSelector />

Revenue Trends with Time Range

import { getRevenueTrendsWithStore } from '@/lib/services/analytics-service';

// Get 30-day revenue trends
const trends = await getRevenueTrendsWithStore('30');

Data Structure

AnalyticsOverview

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

interface RevenueData {
  _id: {
    year: number;
    month: number;
    day: number;
  };
  revenue: number;
  orders: number;
}

ProductPerformance

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