WooNooW/DASHBOARD_PLAN.md

# WooNooW Dashboard Plan

**Last updated:** 2025-10-28  
**Status:** Planning Phase  
**Reference:** WooCommerce Analytics & Reports

---

## 🎯 Overview

The Dashboard will be the central hub for store analytics, providing at-a-glance insights and detailed reports. It follows WooCommerce's analytics structure but with a modern, performant React interface.

---

## 📊 Dashboard Structure

### **Main Dashboard (`/dashboard`)**
**Purpose:** Quick overview of the most critical metrics

#### Key Metrics (Top Row - Cards)
1. **Revenue (Today/24h)**
   - Total sales amount
   - Comparison with yesterday (↑ +15%)
   - Sparkline chart

2. **Orders (Today/24h)**
   - Total order count
   - Comparison with yesterday
   - Breakdown: Completed/Processing/Pending

3. **Average Order Value**
   - Calculated from today's orders
   - Trend indicator

4. **Conversion Rate**
   - Orders / Visitors (if analytics available)
   - Trend indicator

#### Main Chart (Center)
- **Sales Overview Chart** (Last 7/30 days)
  - Line/Area chart showing revenue over time
  - Toggle: Revenue / Orders / Both
  - Date range selector: 7 days / 30 days / This month / Last month / Custom

#### Quick Stats Grid (Below Chart)
1. **Top Products (Today)**
   - List of 5 best-selling products
   - Product name, quantity sold, revenue
   - Link to full Products report

2. **Recent Orders**
   - Last 5 orders
   - Order #, Customer, Status, Total
   - Link to Orders page

3. **Low Stock Alerts**
   - Products below stock threshold
   - Product name, current stock, status
   - Link to Products page

4. **Top Customers**
   - Top 5 customers by total spend
   - Name, orders count, total spent
   - Link to Customers page

---

## 📑 Submenu Pages (Detailed Reports)

### 1. **Revenue** (`/dashboard/revenue`)
**Purpose:** Detailed revenue analysis

#### Features:
- **Date Range Selector** (Custom, presets)
- **Revenue Chart** (Daily/Weekly/Monthly granularity)
- **Breakdown Tables:**
  - Revenue by Product
  - Revenue by Category
  - Revenue by Payment Method
  - Revenue by Shipping Method
- **Comparison Mode:** Compare with previous period
- **Export:** CSV/PDF export

#### Metrics:
- Gross Revenue
- Net Revenue (after refunds)
- Tax Collected
- Shipping Revenue
- Refunds

---

### 2. **Orders** (`/dashboard/orders`)
**Purpose:** Order analytics and trends

#### Features:
- **Orders Chart** (Timeline)
- **Status Breakdown** (Pie/Donut chart)
  - Completed, Processing, Pending, Cancelled, Refunded, Failed
- **Tables:**
  - Orders by Hour (peak times)
  - Orders by Day of Week
  - Average Processing Time
- **Filters:** Status, Date Range, Payment Method

#### Metrics:
- Total Orders
- Average Order Value
- Orders by Status
- Fulfillment Rate
- Cancellation Rate

---

### 3. **Products** (`/dashboard/products`)
**Purpose:** Product performance analysis

#### Features:
- **Top Products Table**
  - Product name, items sold, revenue, stock status
  - Sortable by revenue, quantity, views
- **Category Performance**
  - Revenue and sales by category
  - Tree view for nested categories
- **Product Trends Chart**
  - Sales trend for selected products
- **Stock Analysis**
  - Low stock items
  - Out of stock items
  - Overstocked items (slow movers)

#### Metrics:
- Items Sold
- Revenue per Product
- Stock Status
- Conversion Rate (if analytics available)

---

### 4. **Customers** (`/dashboard/customers`)
**Purpose:** Customer behavior and segmentation

#### Features:
- **Customer Segments**
  - New Customers (first order)
  - Returning Customers
  - VIP Customers (high lifetime value)
  - At-Risk Customers (no recent orders)
- **Top Customers Table**
  - Name, total orders, total spent, last order date
  - Sortable, searchable
- **Customer Acquisition Chart**
  - New customers over time
- **Lifetime Value Analysis**
  - Average LTV
  - LTV distribution

#### Metrics:
- Total Customers
- New Customers (period)
- Average Orders per Customer
- Customer Retention Rate
- Average Customer Lifetime Value

---

### 5. **Coupons** (`/dashboard/coupons`)
**Purpose:** Coupon usage and effectiveness

#### Features:
- **Coupon Performance Table**
  - Coupon code, uses, discount amount, revenue generated
  - ROI calculation
- **Usage Chart**
  - Coupon usage over time
- **Top Coupons**
  - Most used
  - Highest revenue impact
  - Best ROI

#### Metrics:
- Total Discount Amount
- Coupons Used
- Revenue with Coupons
- Average Discount per Order

---

### 6. **Taxes** (`/dashboard/taxes`)
**Purpose:** Tax collection reporting

#### Features:
- **Tax Summary**
  - Total tax collected
  - By tax rate
  - By location (country/state)
- **Tax Chart**
  - Tax collection over time
- **Tax Breakdown Table**
  - Tax rate, orders, tax amount

#### Metrics:
- Total Tax Collected
- Tax by Rate
- Tax by Location
- Average Tax per Order

---

### 7. **Downloads** (`/dashboard/downloads`)
**Purpose:** Digital product download tracking (if applicable)

#### Features:
- **Download Stats**
  - Total downloads
  - Downloads by product
  - Downloads by customer
- **Download Chart**
  - Downloads over time
- **Top Downloaded Products**

#### Metrics:
- Total Downloads
- Unique Downloads
- Downloads per Product
- Average Downloads per Customer

---

## 🛠️ Technical Implementation

### Backend (PHP)

#### New REST Endpoints:
```
GET /woonoow/v1/analytics/overview
GET /woonoow/v1/analytics/revenue
GET /woonoow/v1/analytics/orders
GET /woonoow/v1/analytics/products
GET /woonoow/v1/analytics/customers
GET /woonoow/v1/analytics/coupons
GET /woonoow/v1/analytics/taxes
```

#### Query Parameters:
- `date_start` - Start date (YYYY-MM-DD)
- `date_end` - End date (YYYY-MM-DD)
- `period` - Granularity (day, week, month)
- `compare` - Compare with previous period (boolean)
- `limit` - Results limit for tables
- `orderby` - Sort field
- `order` - Sort direction (asc/desc)

#### Data Sources:
- **HPOS Tables:** `wc_orders`, `wc_order_stats`
- **WooCommerce Analytics:** Leverage existing `wc_admin_*` tables if available
- **Custom Queries:** Optimized SQL for complex aggregations
- **Caching:** Transients for expensive queries (5-15 min TTL)

---

### Frontend (React)

#### Components:
```
admin-spa/src/routes/Dashboard/
├── index.tsx              # Main overview
├── Revenue.tsx            # Revenue report
├── Orders.tsx             # Orders analytics
├── Products.tsx           # Product performance
├── Customers.tsx          # Customer analytics
├── Coupons.tsx            # Coupon reports
├── Taxes.tsx              # Tax reports
└── components/
    ├── StatCard.tsx       # Metric card with trend
    ├── ChartCard.tsx      # Chart container
    ├── DataTable.tsx      # Sortable table
    ├── DateRangePicker.tsx # Date selector
    ├── ComparisonToggle.tsx # Compare mode
    └── ExportButton.tsx   # CSV/PDF export
```

#### Charts (Recharts):
- **LineChart** - Revenue/Orders trends
- **AreaChart** - Sales overview
- **BarChart** - Comparisons, categories
- **PieChart** - Status breakdown, segments
- **ComposedChart** - Multi-metric views

#### State Management:
- **React Query** for data fetching & caching
- **URL State** for filters (date range, sorting)
- **Local Storage** for user preferences (chart type, default period)

---

## 🎨 UI/UX Principles

### Design:
- **Consistent with Orders module** - Same card style, spacing, typography
- **Mobile-first** - Responsive charts and tables
- **Loading States** - Skeleton loaders for charts and tables
- **Empty States** - Helpful messages when no data
- **Error Handling** - ErrorCard component for failures

### Performance:
- **Lazy Loading** - Code-split dashboard routes
- **Optimistic Updates** - Instant feedback
- **Debounced Filters** - Reduce API calls
- **Cached Data** - React Query stale-while-revalidate

### Accessibility:
- **Keyboard Navigation** - Full keyboard support
- **ARIA Labels** - Screen reader friendly
- **Color Contrast** - WCAG AA compliant
- **Focus Indicators** - Clear focus states

---

## 📅 Implementation Phases

### **Phase 1: Foundation** (Week 1) ✅ COMPLETE
- [x] Create backend analytics endpoints (Dummy data ready)
- [x] Implement data aggregation queries (Dummy data structures)
- [x] Set up caching strategy (Zustand + LocalStorage)
- [x] Create base dashboard layout
- [x] Implement StatCard component

### **Phase 2: Main Dashboard** (Week 2) ✅ COMPLETE
- [x] Revenue/Orders/AOV/Conversion cards
- [x] Sales overview chart
- [x] Quick stats grid (Top Products, Recent Orders, etc.)
- [x] Date range selector
- [x] Dummy data toggle system
- [ ] Real-time data updates (Pending API)

### **Phase 3: Revenue & Orders Reports** (Week 3) ✅ COMPLETE
- [x] Revenue detailed page
- [x] Orders analytics page
- [x] Breakdown tables (Product, Category, Payment, Shipping)
- [x] Status distribution charts
- [x] Period selectors
- [ ] Comparison mode (Pending)
- [ ] Export functionality (Pending)
- [ ] Advanced filters (Pending)

### **Phase 4: Products & Customers** (Week 4) ✅ COMPLETE
- [x] Products performance page
- [x] Customer analytics page
- [x] Segmentation logic (New, Returning, VIP, At Risk)
- [x] Stock analysis (Low, Out, Slow Movers)
- [x] LTV calculations and distribution

### **Phase 5: Coupons & Taxes** (Week 5) ✅ COMPLETE
- [x] Coupons report page
- [x] Tax reports page
- [x] ROI calculations
- [x] Location-based breakdowns

### **Phase 6: Polish & Optimization** (Week 6) ⏳ IN PROGRESS
- [x] Mobile responsiveness (All pages responsive)
- [x] Loading states refinement (Skeleton loaders)
- [x] Documentation (PROGRESS_NOTE.md updated)
- [ ] Performance optimization (Pending)
- [ ] Error handling improvements (Pending)
- [ ] User testing (Pending)

### **Phase 7: Real Data Integration** (NEW) ⏳ PENDING
- [ ] Create backend REST API endpoints
- [ ] Wire all pages to real data
- [ ] Keep dummy data toggle for demos
- [ ] Add data refresh functionality
- [ ] Add export functionality (CSV/PDF)
- [ ] Add comparison mode
- [ ] Add custom date range picker

---

## 🔍 Data Models

### Overview Response:
```typescript
{
  revenue: {
    today: number,
    yesterday: number,
    change_percent: number,
    sparkline: number[]
  },
  orders: {
    today: number,
    yesterday: number,
    change_percent: number,
    by_status: {
      completed: number,
      processing: number,
      pending: number,
      // ...
    }
  },
  aov: {
    current: number,
    previous: number,
    change_percent: number
  },
  conversion_rate: {
    current: number,
    previous: number,
    change_percent: number
  },
  chart_data: Array<{
    date: string,
    revenue: number,
    orders: number
  }>,
  top_products: Array<{
    id: number,
    name: string,
    quantity: number,
    revenue: number
  }>,
  recent_orders: Array<{
    id: number,
    number: string,
    customer: string,
    status: string,
    total: number,
    date: string
  }>,
  low_stock: Array<{
    id: number,
    name: string,
    stock: number,
    status: string
  }>,
  top_customers: Array<{
    id: number,
    name: string,
    orders: number,
    total_spent: number
  }>
}
```

---

## 📚 References

### WooCommerce Analytics:
- WooCommerce Admin Analytics (wc-admin)
- WooCommerce Reports API
- Analytics Database Tables

### Design Inspiration:
- Shopify Analytics
- WooCommerce native reports
- Google Analytics dashboard
- Stripe Dashboard

### Libraries:
- **Recharts** - Charts and graphs
- **React Query** - Data fetching
- **date-fns** - Date manipulation
- **Shadcn UI** - UI components

---

## 🚀 Future Enhancements

### Advanced Features:
- **Real-time Updates** - WebSocket for live data
- **Forecasting** - Predictive analytics
- **Custom Reports** - User-defined metrics
- **Scheduled Reports** - Email reports
- **Multi-store** - Compare multiple stores
- **API Access** - Export data via API
- **Webhooks** - Trigger on thresholds
- **Alerts** - Low stock, high refunds, etc.

### Integrations:
- **Google Analytics** - Traffic data
- **Facebook Pixel** - Ad performance
- **Email Marketing** - Campaign ROI
- **Inventory Management** - Stock sync
- **Accounting** - QuickBooks, Xero

---

## ✅ Success Metrics

### Performance:
- Page load < 2s
- Chart render < 500ms
- API response < 1s
- 90+ Lighthouse score

### Usability:
- Mobile-friendly (100%)
- Keyboard accessible
- Screen reader compatible
- Intuitive navigation

### Accuracy:
- Data matches WooCommerce reports
- Real-time sync (< 5 min lag)
- Correct calculations
- No data loss

---

**End of Dashboard Plan**