# Reports & Analytics Dashboard - API Requirements

This document outlines the API endpoints required to make the visual analytics dashboard fully dynamic. All endpoints must support date-based filtering so the UI can switch between "Today", "Yesterday", "This Week", "This Month", and "All Time".

## Global Query Parameters
Every endpoint below should accept the following query parameters to drive the date filter dropdown:
- `timeRange` (String): e.g., `"today"`, `"yesterday"`, `"this_week"`, `"this_month"`, `"all_time"`
- *(Alternative)* `startDate` & `endDate` (ISO 8601 Date Strings): If you prefer absolute date ranges (e.g., `?startDate=2026-05-19&endDate=2026-05-19`)

---

## 1. Top Level KPIs API
Powers the four main stat cards at the top of the dashboard.

**Endpoint:** `GET /api/reports/kpis`
**Description:** Returns the high-level summary metrics for the selected time range, along with the percentage trend compared to the previous equivalent time range (e.g., Today vs Yesterday).

**Response Schema:**
```json
{
  "success": true,
  "data": {
    "totalRevenue": {
      "value": 42800,
      "trend": "+15.2%"
    },
    "totalOrders": {
      "value": 248,
      "trend": "+8.4%"
    },
    "customersServed": {
      "value": 612,
      "trend": "+12.1%"
    },
    "averageOrderValue": {
      "value": 172,
      "trend": "+2.3%"
    }
  }
}
```

---

## 2. Hourly Revenue Trend API
Powers the main vertical bar chart showing revenue over time.

**Endpoint:** `GET /api/reports/revenue-trend`
**Description:** Returns revenue grouped by time intervals. For "Today/Yesterday", group by hours. For "This Week", group by days. For "This Month", group by weeks/days.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    { "timeLabel": "10am", "amount": 1200 },
    { "timeLabel": "12pm", "amount": 4500 },
    { "timeLabel": "2pm", "amount": 8900 },
    { "timeLabel": "4pm", "amount": 3200 },
    { "timeLabel": "6pm", "amount": 6700 },
    { "timeLabel": "8pm", "amount": 8200 },
    { "timeLabel": "10pm", "amount": 4100 }
  ]
}
```
*Note: The frontend will automatically calculate the height percentages based on the maximum amount in the array.*

---

## 3. Payment Splits API
Powers the donut/pie chart showing revenue by payment method.

**Endpoint:** `GET /api/reports/payment-splits`
**Description:** Groups completed orders by payment method and returns the absolute values and percentages.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    { "method": "UPI", "percentage": 55, "totalAmount": 23540 },
    { "method": "Card", "percentage": 30, "totalAmount": 12840 },
    { "method": "Cash", "percentage": 15, "totalAmount": 6420 }
  ]
}
```

---

## 4. High Demand Items API
Powers the horizontal bar chart showing top selling menu items.

**Endpoint:** `GET /api/reports/top-items`
**Query Params:** `?limit=5` (default to 5 items)
**Description:** Returns the top N most ordered menu items by quantity sold.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    {
      "itemName": "Paneer Tikka Masala",
      "quantitySold": 145,
      "revenueGenerated": 36250
    },
    {
      "itemName": "Garlic Naan",
      "quantitySold": 120,
      "revenueGenerated": 8400
    }
    // ... up to 5 items
  ]
}
```

---

## 5. Category Mix API
Powers the pie chart showing sales distribution across menu categories (Food vs Beverage, etc).

**Endpoint:** `GET /api/reports/category-mix`
**Description:** Groups sales by the item's main category.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    { "category": "Main Course", "percentage": 45, "revenue": 19260 },
    { "category": "Starters", "percentage": 25, "revenue": 10700 },
    { "category": "Beverages", "percentage": 20, "revenue": 8560 },
    { "category": "Desserts", "percentage": 10, "revenue": 4280 }
  ]
}
```

---

## 6. Area / Table Performance API
Powers the horizontal bar chart showing which zones or tables are generating the most revenue.

**Endpoint:** `GET /api/reports/table-performance`
**Query Params:** `?limit=4`
**Description:** Groups completed orders by Table or Zone/Area to find the most profitable seating locations.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    { "tableName": "Family Area (T12)", "revenue": 15600 },
    { "tableName": "Table 04 (Window)", "revenue": 12400 },
    { "tableName": "Table 01 (Corner)", "revenue": 9800 },
    { "tableName": "Table 08 (Center)", "revenue": 8200 }
  ]
}
```

---

## 7. Waiter Performance API
Powers the Best Waiters grid cards at the bottom.

**Endpoint:** `GET /api/reports/waiter-performance`
**Query Params:** `?limit=4`
**Description:** Returns the top performing waiters based on number of orders handled and average customer rating (if applicable) or revenue generated.

**Response Schema:**
```json
{
  "success": true,
  "data": [
    {
      "waiterId": "W001",
      "name": "Rahul S.",
      "ordersHandled": 42,
      "rating": 4.8,
      "revenueGenerated": 12500
    },
    {
      "waiterId": "W005",
      "name": "Amit K.",
      "ordersHandled": 38,
      "rating": 4.5,
      "revenueGenerated": 10200
    }
  ]
}
```