Seera/DASHBOARD_SETUP.md

# Modern Dashboard Setup Guide

## Overview
Your React frontend now has a beautiful modern dashboard that consumes data from Frappe Dashboard Chart and Number Card doctypes.

## What's Been Created

### 1. Backend API File
**File**: `frappe_dashboard_api.py`
- Copy this to your Frappe app: `asset_lite/api/dashboard_api.py`
- Contains endpoints:
  - `get_number_cards()` - Returns KPI counts (total assets, work orders by status)
  - `list_dashboard_charts()` - Lists all public Dashboard Chart docs
  - `get_dashboard_chart_data(chart_name)` - Returns chart-ready JSON for any Report-based Dashboard Chart
  - `get_repair_cost_by_item(year)` - Example specialized chart endpoint

### 2. Frontend Components

#### `src/pages/ModernDashboard.tsx` (NEW)
Modern dashboard matching your reference image with:
- Gradient KPI cards (pink, cyan, emerald)
- Tab switcher (Variation 1 / Variation 2)
- Work Order Status chart with bar visualization
- Bandwidth Reports chart (multi-dataset bars)
- Progress bars for metrics
- Message statistics cards
- Author rankings with trend indicators

#### `src/components/SimpleChart.tsx`
Lightweight SVG-based chart renderer:
- Bar charts (single & stacked)
- Pie charts
- No external dependencies

#### `src/components/ChartTile.tsx`
Reusable tile that fetches and displays a Dashboard Chart by name

### 3. API Integration

#### `src/config/api.ts`
Added endpoints:
```typescript
DASHBOARD_NUMBER_CARDS: '/api/method/asset_lite.api.dashboard_api.get_number_cards'
DASHBOARD_LIST_CHARTS: '/api/method/asset_lite.api.dashboard_api.list_dashboard_charts'
DASHBOARD_CHART_DATA: '/api/method/asset_lite.api.dashboard_api.get_dashboard_chart_data'
```

#### `src/services/apiService.ts`
Added methods:
- `getNumberCards()`
- `listDashboardCharts(publicOnly)`
- `getDashboardChartData(chartName, filters)`

#### `src/hooks/useApi.ts`
Added hooks:
- `useNumberCards()` - Fetches KPI card data
- `useDashboardChart(chartName, filters)` - Fetches specific chart data
- `useChartsList(publicOnly)` - Lists available charts

### 4. Routing
**File**: `src/App.tsx`
- `/dashboard` route already points to `ModernDashboard` component
- Protected by authentication
- Includes sidebar navigation

## Installation Steps

### Step 1: Deploy Backend API
```bash
# Navigate to your Frappe app directory
cd frappe-bench/apps/asset_lite

# Create the api directory if it doesn't exist
mkdir -p asset_lite/api

# Copy the Python file
cp /path/to/frappe_dashboard_api.py asset_lite/api/dashboard_api.py

# Restart your Frappe server
bench restart
```

### Step 2: Verify Dashboard Charts in Frappe
Ensure these Dashboard Charts exist and are marked as "Public":
- Up & Down Time Chart
- Work Order Status Chart
- Maintenance - Asset wise Count
- Asset Maintenance Assignees Status Count
- Asset Maintenance Frequency Chart
- PPM Status
- PPM Template Counts
- Repair Cost

Each chart should:
- Chart Type: "Report"
- Use Report Chart: ✓ checked
- Have a Report Name configured
- Have X Field set
- Have Y Axis fields configured in child table
- Is Public: ✓ checked

### Step 3: Test the API Endpoints
```bash
# Test number cards
curl -X GET "https://seeraasm-med.seeraarabia.com/api/method/asset_lite.api.dashboard_api.get_number_cards" \
  -H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET"

# Test chart data
curl -X GET "https://seeraasm-med.seeraarabia.com/api/method/asset_lite.api.dashboard_api.get_dashboard_chart_data?chart_name=Work%20Order%20Status%20Chart" \
  -H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET"
```

### Step 4: Run Frontend
```bash
cd frappe-frontend
npm install
npm run dev
```

Navigate to: `http://localhost:5173/dashboard`

## Dashboard Features

### KPI Cards (Top Row)
- **Total Assets**: Pink gradient, shows count from Asset doctype
- **Work Orders**: Cyan gradient, shows open + in progress count
- **Completed**: Green gradient, shows completed work orders

### Charts Section
- **Work Order Status**: Bar chart from "Work Order Status Chart" Dashboard Chart
- **Bandwidth Reports**: Multi-dataset chart from "Maintenance - Asset wise Count"
- Both support tab switching and dynamic data loading

### Additional Sections
- Top Authors ranking (mock data for now)
- Progress metrics with colored bars
- Message statistics at bottom

## Customization

### Change Chart Names
Edit `src/pages/ModernDashboard.tsx` lines with `useDashboardChart`:
```typescript
const { data: workOrderChart } = useDashboardChart('Your Chart Name Here');
```

### Add More KPI Cards
1. Add new field in backend `get_number_cards()` function
2. Update TypeScript interface in `src/services/apiService.ts`
3. Add card in `ModernDashboard.tsx` KPI grid

### Customize Colors
Tailwind gradient classes used:
- `from-pink-400 to-pink-300`
- `from-cyan-400 to-cyan-300`
- `from-emerald-400 to-emerald-300`

Change these to any Tailwind color you want.

### Add Filters to Charts
Pass filters to chart hook:
```typescript
const { data: chart } = useDashboardChart('Chart Name', {
  from_date: '2025-01-01',
  to_date: '2025-12-31',
  status: 'Open'
});
```

## Troubleshooting

### Charts Not Loading
1. Check browser console for API errors
2. Verify Dashboard Chart docname is correct (case-sensitive)
3. Ensure chart is marked "Public" or user has permission
4. Check that Report exists and returns data

### Number Cards Show Zero
1. Verify Work Order statuses match those in `get_number_cards()` function
2. Adjust status filters in Python code if your statuses differ:
```python
work_orders_open = frappe.db.count("Work Order", {"status": ["in", ["Your", "Custom", "Statuses"]]})
```

### CORS Errors
1. Check Vite proxy configuration in `vite.config.ts`
2. Ensure Frappe CORS settings allow your frontend domain
3. Verify cookies are being sent (credentials: 'include')

## API Reference

### GET /api/method/asset_lite.api.dashboard_api.get_number_cards
Returns:
```json
{
  "total_assets": 123,
  "work_orders_open": 7,
  "work_orders_in_progress": 3,
  "work_orders_completed": 42
}
```

### GET /api/method/asset_lite.api.dashboard_api.get_dashboard_chart_data
Params:
- `chart_name` (required): Dashboard Chart docname
- `report_filters` (optional): JSON string of filters

Returns:
```json
{
  "labels": ["A", "B", "C"],
  "datasets": [
    {
      "name": "Series 1",
      "values": [10, 20, 15],
      "color": "#4F46E5"
    }
  ],
  "type": "Bar",
  "options": {},
  "source": {"report": "Report Name"}
}
```

## Next Steps

1. **Replace Mock Data**: Update TOP AUTHORS section with real user activity data
2. **Add Real-time Updates**: Use WebSocket or polling to refresh charts every N seconds
3. **Add Date Range Picker**: Let users filter charts by date range
4. **Export Features**: Add PDF/Excel export for charts
5. **Drill-down**: Make chart bars/slices clickable to view detail pages
6. **Responsive Design**: Already responsive, but test on mobile/tablet
7. **Dark Mode**: Add theme toggle using Tailwind dark: classes

## Support

If you encounter issues:
1. Check Frappe logs: `bench logs`
2. Check browser console for frontend errors
3. Verify API responses in Network tab
4. Ensure all Dashboard Charts are properly configured in Frappe

---

**Created**: 2025-10-30
**Version**: 1.0
**Frontend**: React + TypeScript + Vite + TailwindCSS
**Backend**: Frappe v15+ with custom API module