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

• Create backend analytics endpoints (Dummy data ready)
• Implement data aggregation queries (Dummy data structures)
• Set up caching strategy (Zustand + LocalStorage)
• Create base dashboard layout
• Implement StatCard component

Phase 2: Main Dashboard (Week 2) ✅ COMPLETE

• Revenue/Orders/AOV/Conversion cards
• Sales overview chart
• Quick stats grid (Top Products, Recent Orders, etc.)
• Date range selector
• Dummy data toggle system
• Real-time data updates (Pending API)

Phase 3: Revenue & Orders Reports (Week 3) ✅ COMPLETE

• Revenue detailed page
• Orders analytics page
• Breakdown tables (Product, Category, Payment, Shipping)
• Status distribution charts
• Period selectors
• Comparison mode (Pending)
• Export functionality (Pending)
• Advanced filters (Pending)

Phase 4: Products & Customers (Week 4) ✅ COMPLETE

• Products performance page
• Customer analytics page
• Segmentation logic (New, Returning, VIP, At Risk)
• Stock analysis (Low, Out, Slow Movers)
• LTV calculations and distribution

Phase 5: Coupons & Taxes (Week 5) ✅ COMPLETE

• Coupons report page
• Tax reports page
• ROI calculations
• Location-based breakdowns

Phase 6: Polish & Optimization (Week 6) ⏳ IN PROGRESS

• Mobile responsiveness (All pages responsive)
• Loading states refinement (Skeleton loaders)
• 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:

{
  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