WooNooW/DASHBOARD_IMPLEMENTATION.md

📊 Dashboard Implementation Guide

Last updated: 2025-11-03 14:50 GMT+7
Status: In Progress
Reference: DASHBOARD_PLAN.md

---

🎯 Overview

This document tracks the implementation of the WooNooW Dashboard module with all submenus as planned in DASHBOARD_PLAN.md. We're implementing a dummy data toggle system to allow visualization of charts even when stores have no data yet.

---

✅ Completed

1. Main Dashboard (/dashboard) ✅

Status: Complete with dummy data
File: admin-spa/src/routes/Dashboard/index.tsx

Features:

• ✅ 4 metric cards (Revenue, Orders, Avg Order Value, Conversion Rate)
• ✅ Unified period selector (7/14/30 days)
• ✅ Interactive Sales Overview chart (Revenue/Orders/Both)
• ✅ Interactive Order Status pie chart with dropdown
• ✅ Top Products & Customers (tabbed)
• ✅ Low Stock Alert banner (edge-to-edge)
• ✅ Fully responsive (desktop/tablet/mobile)
• ✅ Dark mode support
• ✅ Proper currency formatting

2. Dummy Data Toggle System ✅

Status: Complete
Files:

• admin-spa/src/lib/useDummyData.ts - Zustand store with persistence
• admin-spa/src/components/DummyDataToggle.tsx - Toggle button component

Features:

• ✅ Global state management with Zustand
• ✅ LocalStorage persistence
• ✅ Toggle button in dashboard header
• ✅ Visual indicator (Database icon vs DatabaseZap icon)
• ✅ Works across all dashboard pages

Usage:

import { useDummyData } from '@/lib/useDummyData';

function MyComponent() {
  const useDummy = useDummyData();
  
  const data = useDummy ? DUMMY_DATA : realData;
  // ...
}

---

🚧 In Progress

Shared Components

Creating reusable components for all dashboard pages:

Components to Create:

• StatCard.tsx - Metric card with trend indicator
• ChartCard.tsx - Chart container with title and filters
• DataTable.tsx - Sortable, searchable table
• DateRangePicker.tsx - Custom date range selector
• ComparisonToggle.tsx - Compare with previous period
• ExportButton.tsx - CSV/PDF export functionality
• LoadingSkeleton.tsx - Loading states for charts/tables
• EmptyState.tsx - No data messages

---

📋 Pending Implementation

1. Revenue Report (/dashboard/revenue)

Priority: High
Estimated Time: 2-3 days

Features to Implement:

• Revenue chart with granularity selector (daily/weekly/monthly)
• Gross vs Net revenue comparison
• Revenue breakdown tables:
  • By Product
  • By Category
  • By Payment Method
  • By Shipping Method
• Tax collected display
• Refunds tracking
• Comparison mode (vs previous period)
• Export functionality

Dummy Data Structure:

{
  overview: {
    gross_revenue: number,
    net_revenue: number,
    tax: number,
    shipping: number,
    refunds: number,
    change_percent: number
  },
  chart_data: Array<{
    date: string,
    gross: number,
    net: number,
    refunds: number
  }>,
  by_product: Array<{
    id: number,
    name: string,
    revenue: number,
    orders: number,
    refunds: number
  }>,
  by_category: Array<{
    id: number,
    name: string,
    revenue: number,
    percentage: number
  }>,
  by_payment_method: Array<{
    method: string,
    orders: number,
    revenue: number
  }>,
  by_shipping_method: Array<{
    method: string,
    orders: number,
    revenue: number
  }>
}

---

2. Orders Analytics (/dashboard/orders)

Priority: High
Estimated Time: 2-3 days

Features to Implement:

• Orders timeline chart
• Status breakdown pie chart
• Orders by hour heatmap
• Orders by day of week chart
• Average processing time
• Fulfillment rate metric
• Cancellation rate metric
• Filters (status, payment method, date range)

Dummy Data Structure:

{
  overview: {
    total_orders: number,
    avg_order_value: number,
    fulfillment_rate: number,
    cancellation_rate: number,
    avg_processing_time: string
  },
  chart_data: Array<{
    date: string,
    orders: number,
    completed: number,
    cancelled: number
  }>,
  by_status: Array<{
    status: string,
    count: number,
    percentage: number,
    color: string
  }>,
  by_hour: Array<{
    hour: number,
    orders: number
  }>,
  by_day_of_week: Array<{
    day: string,
    orders: number
  }>
}

---

3. Products Performance (/dashboard/products)

Priority: Medium
Estimated Time: 3-4 days

Features to Implement:

• Top products table (sortable by revenue/quantity/views)
• Category performance breakdown
• Product trends chart (multi-select products)
• Stock analysis:
  • Low stock items
  • Out of stock items
  • Slow movers (overstocked)
• Search and filters
• Export functionality

Dummy Data Structure:

{
  overview: {
    items_sold: number,
    revenue: number,
    avg_price: number,
    low_stock_count: number,
    out_of_stock_count: number
  },
  top_products: Array<{
    id: number,
    name: string,
    image: string,
    items_sold: number,
    revenue: number,
    stock: number,
    status: string,
    views: number
  }>,
  by_category: Array<{
    id: number,
    name: string,
    products_count: number,
    revenue: number,
    items_sold: number
  }>,
  stock_analysis: {
    low_stock: Array<Product>,
    out_of_stock: Array<Product>,
    slow_movers: Array<Product>
  }
}

---

4. Customers Analytics (/dashboard/customers)

Priority: Medium
Estimated Time: 3-4 days

Features to Implement:

• Customer segments (New, Returning, VIP, At-Risk)
• Top customers table
• Customer acquisition chart
• Lifetime value analysis
• Retention rate metric
• Average orders per customer
• Search and filters

Dummy Data Structure:

{
  overview: {
    total_customers: number,
    new_customers: number,
    returning_customers: number,
    avg_ltv: number,
    retention_rate: number,
    avg_orders_per_customer: number
  },
  segments: {
    new: number,
    returning: number,
    vip: number,
    at_risk: number
  },
  top_customers: Array<{
    id: number,
    name: string,
    email: string,
    orders: number,
    total_spent: number,
    avg_order_value: number,
    last_order_date: string,
    segment: string
  }>,
  acquisition_chart: Array<{
    date: string,
    new_customers: number,
    returning_customers: number
  }>,
  ltv_distribution: Array<{
    range: string,
    count: number
  }>
}

---

5. Coupons Report (/dashboard/coupons)

Priority: Low
Estimated Time: 2 days

Features to Implement:

• Coupon performance table
• Usage chart over time
• ROI calculation
• Top coupons (most used, highest revenue, best ROI)
• Filters and search

Dummy Data Structure:

{
  overview: {
    total_discount: number,
    coupons_used: number,
    revenue_with_coupons: number,
    avg_discount_per_order: number
  },
  coupons: Array<{
    id: number,
    code: string,
    type: string,
    amount: number,
    uses: number,
    discount_amount: number,
    revenue_generated: number,
    roi: number
  }>,
  usage_chart: Array<{
    date: string,
    uses: number,
    discount: number
  }>
}

---

6. Taxes Report (/dashboard/taxes)

Priority: Low
Estimated Time: 1-2 days

Features to Implement:

• Tax summary (total collected)
• Tax by rate breakdown
• Tax by location (country/state)
• Tax collection chart
• Export for accounting

Dummy Data Structure:

{
  overview: {
    total_tax: number,
    avg_tax_per_order: number,
    orders_with_tax: number
  },
  by_rate: Array<{
    rate: string,
    percentage: number,
    orders: number,
    tax_amount: number
  }>,
  by_location: Array<{
    country: string,
    state: string,
    orders: number,
    tax_amount: number
  }>,
  chart_data: Array<{
    date: string,
    tax: number
  }>
}

---

🗂️ File Structure

admin-spa/src/
├── routes/
│   └── Dashboard/
│       ├── index.tsx              ✅ Main overview (complete)
│       ├── Revenue.tsx            ⏳ Revenue report (pending)
│       ├── Orders.tsx             ⏳ Orders analytics (pending)
│       ├── Products.tsx           ⏳ Product performance (pending)
│       ├── Customers.tsx          ⏳ Customer analytics (pending)
│       ├── Coupons.tsx            ⏳ Coupon reports (pending)
│       ├── Taxes.tsx              ⏳ Tax reports (pending)
│       ├── components/
│       │   ├── StatCard.tsx       ⏳ Metric card (pending)
│       │   ├── ChartCard.tsx      ⏳ Chart container (pending)
│       │   ├── DataTable.tsx      ⏳ Sortable table (pending)
│       │   ├── DateRangePicker.tsx ⏳ Date selector (pending)
│       │   ├── ComparisonToggle.tsx ⏳ Compare mode (pending)
│       │   └── ExportButton.tsx   ⏳ Export (pending)
│       └── data/
│           ├── dummyRevenue.ts    ⏳ Revenue dummy data (pending)
│           ├── dummyOrders.ts     ⏳ Orders dummy data (pending)
│           ├── dummyProducts.ts   ⏳ Products dummy data (pending)
│           ├── dummyCustomers.ts  ⏳ Customers dummy data (pending)
│           ├── dummyCoupons.ts    ⏳ Coupons dummy data (pending)
│           └── dummyTaxes.ts      ⏳ Taxes dummy data (pending)
├── components/
│   ├── DummyDataToggle.tsx        ✅ Toggle button (complete)
│   └── ui/
│       ├── tabs.tsx               ✅ Tabs component (complete)
│       └── tooltip.tsx            ⏳ Tooltip (needs @radix-ui package)
└── lib/
    └── useDummyData.ts            ✅ Dummy data store (complete)

---

🔧 Technical Stack

Frontend:

• React 18 + TypeScript
• Recharts 3.3.0 (charts)
• TanStack Query (data fetching)
• Zustand (state management)
• Shadcn UI (components)
• Tailwind CSS (styling)

Backend (Future):

• REST API endpoints (/woonoow/v1/analytics/*)
• HPOS tables integration
• Query optimization with caching
• Transients for expensive queries

---

📅 Implementation Timeline

Week 1: Foundation ✅

• Main Dashboard with dummy data
• Dummy data toggle system
• Shared component planning

Week 2: Shared Components (Current)

• Create all shared components
• Create dummy data files
• Set up routing for submenus

Week 3: Revenue & Orders

• Revenue report page
• Orders analytics page
• Export functionality

Week 4: Products & Customers

• Products performance page
• Customers analytics page
• Advanced filters

Week 5: Coupons & Taxes

• Coupons report page
• Taxes report page
• Final polish

Week 6: Real Data Integration

• Create backend API endpoints
• Wire all pages to real data
• Keep dummy data toggle for demos
• Performance optimization

---

🎯 Next Steps

Immediate (This Week):

1. ✅ Create dummy data toggle system
2. ⏳ Create shared components (StatCard, ChartCard, DataTable)
3. ⏳ Set up routing for all dashboard submenus
4. ⏳ Create dummy data files for each page

Short Term (Next 2 Weeks):

1. Implement Revenue report page
2. Implement Orders analytics page
3. Add export functionality
4. Add comparison mode

Long Term (Month 2):

1. Implement remaining pages (Products, Customers, Coupons, Taxes)
2. Create backend API endpoints
3. Wire to real data
4. Performance optimization
5. User testing

---

📝 Notes

Dummy Data Toggle Benefits:

1. Development: Easy to test UI without real data
2. Demos: Show potential to clients/stakeholders
3. New Stores: Visualize what analytics will look like
4. Testing: Consistent data for testing edge cases

Design Principles:

1. Consistency: All pages follow same design language
2. Performance: Lazy load routes, optimize queries
3. Accessibility: Keyboard navigation, screen readers
4. Responsiveness: Mobile-first approach
5. UX: Clear loading states, helpful empty states

---

Status: Ready to proceed with shared components and submenu pages!
Next Action: Create shared components (StatCard, ChartCard, DataTable)