# Admin Dashboard API Documentation

## GET /v1/admin/dashboard-stats

This endpoint provides comprehensive statistics for the admin dashboard, including activity metrics, user statistics, and detailed breakdowns with support for filtering and pagination.

### Query Parameters

| Parameter    | Type   | Required | Default | Description                                                          |
| ------------ | ------ | -------- | ------- | -------------------------------------------------------------------- |
| `page`       | number | No       | 1       | Page number for pagination                                           |
| `limit`      | number | No       | 50      | Number of activities per page (max 100)                              |
| `startDate`  | string | No       | -       | Start date for filtering (ISO date string)                           |
| `endDate`    | string | No       | -       | End date for filtering (ISO date string)                             |
| `actionType` | string | No       | -       | Filter by action type (LOGIN, LOGOUT, SIGNUP, CHAT, CONTACT_SUPPORT) |

### Response Format

```json
{
  "success": true,
  "message": "Dashboard statistics retrieved successfully",
  "data": {
    "summary": {
      "totalActivity": 1250,
      "activeUsers": 89,
      "mostFrequentActionType": {
        "actionType": "LOGIN",
        "count": 450
      },
      "todaysActivity": 45
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1250,
      "totalPages": 25,
      "hasNext": true,
      "hasPrev": false
    },
    "filters": {
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-15T23:59:59.999Z",
      "actionType": "LOGIN"
    },
    "actionTypeBreakdown": [
      {
        "actionType": "LOGIN",
        "count": 450,
        "percentage": 36
      },
      {
        "actionType": "CHAT",
        "count": 380,
        "percentage": 30
      },
      {
        "actionType": "SIGNUP",
        "count": 200,
        "percentage": 16
      },
      {
        "actionType": "LOGOUT",
        "count": 150,
        "percentage": 12
      },
      {
        "actionType": "CONTACT_SUPPORT",
        "count": 70,
        "percentage": 6
      }
    ],
    "todaysActivityBreakdown": [
      {
        "actionType": "LOGIN",
        "count": 15,
        "percentage": 33
      },
      {
        "actionType": "CHAT",
        "count": 12,
        "percentage": 27
      },
      {
        "actionType": "SIGNUP",
        "count": 8,
        "percentage": 18
      },
      {
        "actionType": "LOGOUT",
        "count": 6,
        "percentage": 13
      },
      {
        "actionType": "CONTACT_SUPPORT",
        "count": 4,
        "percentage": 9
      }
    ],
    "recentActivities": [
      {
        "id": "clx1234567890",
        "action": "User logged in successfully",
        "actionType": "LOGIN",
        "email": "user@example.com",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "user": {
          "id": "user123",
          "email": "user@example.com",
          "fullName": "John Doe",
          "isActive": true
        }
      }
    ]
  }
}
```

### Data Structure

#### Summary

- **totalActivity**: Total number of all activities recorded in the system (or filtered by date)
- **activeUsers**: Number of users who have performed at least one action (or filtered by date)
- **mostFrequentActionType**: The action type that occurs most frequently
- **todaysActivity**: Number of activities performed today

#### Pagination

- **page**: Current page number
- **limit**: Number of items per page
- **total**: Total number of activities matching the filters
- **totalPages**: Total number of pages
- **hasNext**: Whether there's a next page
- **hasPrev**: Whether there's a previous page

#### Filters

- **startDate**: Applied start date filter
- **endDate**: Applied end date filter
- **actionType**: Applied action type filter

#### Action Type Breakdown

- **actionType**: Type of action (LOGIN, LOGOUT, SIGNUP, CHAT, CONTACT_SUPPORT)
- **count**: Number of occurrences
- **percentage**: Percentage of total activities

#### Today's Activity Breakdown

- Similar structure to action type breakdown but only for today's activities

#### Recent Activities

- **id**: Unique identifier for the activity
- **action**: Description of the action performed
- **actionType**: Type of action
- **email**: Email associated with the action
- **createdAt**: Timestamp when the action occurred
- **user**: User details (if available)

### Action Types

- **LOGIN**: User login activities
- **LOGOUT**: User logout activities
- **SIGNUP**: New user registration
- **CHAT**: AI chat interactions
- **CONTACT_SUPPORT**: Contact support form submissions

### Usage Examples

#### Basic Request

```bash
curl -X GET http://localhost:3000/v1/admin/dashboard-stats \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

#### With Pagination

```bash
curl -X GET "http://localhost:3000/v1/admin/dashboard-stats?page=2&limit=25" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

#### With Date Filtering

```bash
curl -X GET "http://localhost:3000/v1/admin/dashboard-stats?startDate=2025-01-01T00:00:00.000Z&endDate=2025-01-15T23:59:59.999Z" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

#### With Action Type Filter

```bash
curl -X GET "http://localhost:3000/v1/admin/dashboard-stats?actionType=LOGIN" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

#### Combined Filters

```bash
curl -X GET "http://localhost:3000/v1/admin/dashboard-stats?page=1&limit=20&startDate=2025-01-01T00:00:00.000Z&actionType=CHAT" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

### Notes

- The API returns up to 50 activities per page by default (max 100)
- Percentages are rounded to the nearest integer
- Today's activities are calculated based on the server's timezone
- Active users are defined as users who have performed at least one action
- Date filters use ISO date strings (YYYY-MM-DDTHH:mm:ss.sssZ)
- When date filters are applied, all statistics (except today's activity) are calculated within the date range
- The `todaysActivity` and `todaysActivityBreakdown` are always calculated for the current day regardless of date filters