MIGRATION_GUIDE.md

Migration Guide: Old Widget System → New Chart Widget System

Overview

The old widget system has been replaced with a comprehensive chart widget implementation that provides:

• Better organization and structure
• Role-based access control
• Redis caching support
• 9 pre-built chart widgets
• Improved performance and maintainability

What Changed

Files Removed

• ❌ app/schemas/widget_schema.py → Replaced by app/schemas/chart_widget_schema.py
• ❌ app/services/widget_service.py → Replaced by app/services/chart_widget_service.py
• ❌ app/routers/widget_router.py → Replaced by app/routers/chart_widget_router.py

Files Added

• ✅ app/schemas/chart_widget_schema.py - New schema definitions
• ✅ app/services/chart_widget_service.py - New service with 9 widget handlers
• ✅ app/repositories/chart_widget_repository.py - New repository for database queries
• ✅ app/routers/chart_widget_router.py - New router with role-based endpoints

Router Changes in app/app.py

Before:

from app.routers.widget_router import router as widget_router
app.include_router(widget_router, prefix="/api/v1/widgets", tags=["Widgets"])

After:

from app.routers.chart_widget_router import router as chart_widget_router
app.include_router(chart_widget_router, prefix="/api/v1/charts", tags=["Chart Widgets"])

API Endpoint Changes

Old Endpoints (Removed)

POST /api/v1/widgets/revenue-chart

New Endpoints (Available)

POST /api/v1/charts/revenue-trend
POST /api/v1/charts/gross-margin-trend
POST /api/v1/charts/channel-mix
POST /api/v1/charts/top-skus
POST /api/v1/charts/inventory-status
POST /api/v1/charts/top-selling-products
POST /api/v1/charts/staff-performance
POST /api/v1/charts/my-sales-trend
POST /api/v1/charts/my-top-products
POST /api/v1/charts/widget (Universal endpoint)

Migration Steps for Frontend/API Consumers

1. Update Base URL

Old:

const baseUrl = '/api/v1/widgets';

New:

const baseUrl = '/api/v1/charts';

2. Update Request Format

Old Request:

{
  "widget_id": "wid_revenue_001",
  "time_range": "last_12_months",
  "chart_type": "line"
}

New Request (Same format, different endpoint):

{
  "widget_id": "wid_revenue_trend_12m_001",
  "months": 12,
  "chart_type": "line"
}

3. Update Widget IDs

Old Widget ID	New Widget ID	Endpoint
wid_revenue_001	wid_revenue_trend_12m_001	/charts/revenue-trend
N/A	wid_gross_margin_trend_12m_001	/charts/gross-margin-trend
N/A	wid_channel_mix_001	/charts/channel-mix
N/A	wid_top_5_skus_001	/charts/top-skus
N/A	wid_inventory_status_001	/charts/inventory-status
N/A	wid_top_selling_products_30d_001	/charts/top-selling-products
N/A	wid_staff_performance_001	/charts/staff-performance
N/A	wid_personal_sales_trend_30d_001	/charts/my-sales-trend
N/A	wid_top_products_sold_by_me_001	/charts/my-top-products

4. Update Response Handling

Old Response Structure:

{
  "widget_id": "wid_revenue_001",
  "widget_type": "chart",
  "chart_data": {
    "chart_type": "line",
    "series": [...]
  },
  "summary": {...}
}

New Response Structure (Wrapped in success response):

{
  "success": true,
  "message": "Chart widget retrieved successfully",
  "data": {
    "widget_id": "wid_revenue_trend_12m_001",
    "type": "chart",
    "title": "Revenue Trend (12 Months)",
    "chart_type": "line",
    "series": [...],
    "summary": {...},
    "cached": false
  }
}

5. Example Migration Code

Old Code:

// Old implementation
async function fetchRevenueChart() {
  const response = await fetch('/api/v1/widgets/revenue-chart', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      widget_id: 'wid_revenue_001',
      time_range: 'last_12_months',
      chart_type: 'line'
    })
  });
  
  const data = await response.json();
  return data;
}

New Code:

// New implementation
async function fetchRevenueChart() {
  const response = await fetch('/api/v1/charts/revenue-trend', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      widget_id: 'wid_revenue_trend_12m_001',
      months: 12,
      chart_type: 'line'
    })
  });
  
  const result = await response.json();
  return result.data; // Note: data is now nested in result.data
}

Benefits of New System

1. Role-Based Access Control

Each widget now has explicit role requirements:

• Admin-only widgets (e.g., Gross Margin)
• Manager widgets (e.g., Staff Performance)
• Associate widgets (e.g., My Sales Trend)

2. Caching Support

All widgets now support Redis caching:

// Enable caching (default)
fetch('/api/v1/charts/revenue-trend?use_cache=true', {...})

// Bypass cache
fetch('/api/v1/charts/revenue-trend?use_cache=false', {...})

3. Better Performance

• Database queries optimized
• Proper indexing recommendations
• Configurable cache TTL per widget type

4. Comprehensive Widget Library

9 pre-built widgets covering:

• Financial metrics (Revenue, Margin)
• Sales analytics (Top products, channels)
• Inventory management
• Staff performance
• Personal dashboards

5. Universal Endpoint

Single endpoint for all widgets:

// Works for any widget based on widget_id
fetch('/api/v1/charts/widget', {
  method: 'POST',
  body: JSON.stringify({
    widget_id: 'wid_revenue_trend_12m_001'
  })
})

Testing After Migration

1. Run Test Suite

cd insightfy-bloom-ms-ans
python test_chart_widgets.py

2. Test API Endpoints

./test_chart_widgets_api.sh http://localhost:8000 YOUR_JWT_TOKEN

3. Verify Each Widget

Check that all 9 widgets return data correctly for your merchant.

Rollback Plan

If you need to rollback temporarily:

1. Restore old files from git:

git checkout HEAD~1 -- app/schemas/widget_schema.py
git checkout HEAD~1 -- app/services/widget_service.py
git checkout HEAD~1 -- app/routers/widget_router.py

2. Update app/app.py:

from app.routers.widget_router import router as widget_router
app.include_router(widget_router, prefix="/api/v1/widgets", tags=["Widgets"])

3. Restart the service

Support & Documentation

• Full Documentation: CHART_WIDGETS_README.md
• Quick Start: CHART_WIDGETS_QUICK_START.md
• Widget Config: chart_widgets_config.json
• Test Scripts: test_chart_widgets.py, test_chart_widgets_api.sh

Timeline

• Deprecated: Old widget system (widget_router.py)
• Current: New chart widget system (chart_widget_router.py)
• Removal: Old files removed in this commit

Questions?

Contact the development team or refer to the documentation files for detailed information about the new chart widget system.