# 📊 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:**
```typescript
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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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 ✅
- [x] Main Dashboard with dummy data
- [x] Dummy data toggle system
- [x] 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)