# Support Desk Overall Flow

This document explains the complete flow of the Support Desk module: UI behavior, API calls, backend processing, data source selection, and database usage.

## 1) Entry Point and Main Files

- Filament resource:
  - `app/Filament/Resources/TicketAdminResource.php`
  - Page slug: `ticket-admin`
- Filament page view:
  - `resources/views/filament/resources/ticket-admin-resource/pages/ticket-admin.blade.php`
- API controller:
  - `app/Http/Controllers/Support/SupportWidgetController.php`
- API routes:
  - `routes/api.php` (`/admin/api/support/*`)

## 2) UI Structure (Support Desk Page)

The page has **4 top-level tabs**:

1. Help Center
2. Articles
3. Ticketing
4. Contact Reasons

Ticketing also has inner tabs for listing:

- `unresolved`
- `resolved`
- `refunds`
- `coupons`
- `vouchers`

## 3) Filter Flow

Shared filters (top filter row):

- Date range (`today`, `7_days`, `mtd`, `30_days`, `quarterly`, `half_yearly`, `last_year`, `ytd`, `custom`)
- Custom date range (`dashboard-start-date`, `dashboard-end-date`) when `custom` is selected
- Device type multi-select (`desktop`, `mobile`, `smart tv`, `tablet`)

Filter behavior:

- `Search`:
  - Forces dashboard refresh
  - Reloads ticket listing endpoint with same filters
- `Reset`:
  - Resets date/device filters
  - Forces dashboard refresh
  - Reloads ticket listing with reset filters

## 4) Frontend Runtime Flow

Inside `ticket-admin.blade.php`:

1. On `DOMContentLoaded`:
   - Reads/gets Bearer token
   - Initializes category dropdown
   - Loads dashboard data (`loadDashboardData(true)`)
   - Initializes DataTable when active tab is `ticketing`

2. Top-level tab click:
   - Switches panel visibility
   - Resizes charts
   - **Does not fetch dashboard data again** (optimized)
   - If switching to ticketing: reload/init table

3. Dashboard caching:
   - `loadDashboardData(forceRefresh = false)` caches by filter key:
     - `date_from`
     - `date_to`
     - `device_types`
   - If filters unchanged and data already loaded, API request is skipped.

## 5) API Endpoints Used

Main Support Desk endpoints:

- `GET /admin/api/support/dashboard-detail`
- `GET /admin/api/support/tickets/get-listing`
- `POST /admin/api/support/tickets/create`
- `POST /admin/api/support/tickets/{id}/update`
- `POST /admin/api/support/tickets/{id}/escalate`
- `GET /admin/api/support/tickets/{id}/details`
- `POST /admin/api/support/tickets/{id}/messages`
- `POST /admin/api/support/tickets/{id}/attachments`
- `GET /admin/api/support/customers/search`
- `GET /admin/api/support/categories`
- `GET /admin/api/support/assignees`

Token endpoint:

- `GET /admin/api/tokens/current`

## 6) Backend Data Flow (`SupportWidgetController`)

### A) Dashboard

`getDashboardDetail()` returns:

- Ticketing block:
  - KPIs
  - Status chart
  - Category chart
  - Volume trend
- Help Center block
- Articles block
- Contact Reasons block

### B) Data Source Resolution (ClickHouse tickets)

Support dashboard and ticketing endpoints read from ClickHouse-backed support tables through:

- `App\Services\Support\SupportDeskClickhouseService::listTickets(...)`

This powers:

- `buildKpis(...)`
- `buildStatusChart(...)`
- `buildCategoryChart(...)`
- `buildVolumeTrend(...)`
- `buildHelpCenterData(...)`
- `buildArticlesData(...)`
- `buildContactReasonsData(...)`

## 7) Database Tables in Current Support Desk Flow

Primary support tables used by current flow:

- `support_tickets`
- `ticket_messages`
- `ticket_history`
- `ticket_attachments`
- `customers`
- `client_users`

## 8) Performance Strategy

Performance is improved by:

- Frontend dashboard response caching by filter key
- No dashboard re-fetch on top-level tab switch
- ClickHouse-backed support reads for dashboard/listing queries
- Targeted indexes on ticket and analytics columns