# Monitoring Dashboard — Developer Handoff

**Date:** 2026-03-05
**For:** Developer picking up the Monitoring Dashboard redesign tasks

---

## Read These First

Before touching any code, read these two documents in order:

1. **`Monitoring-Dashboard-Feature-Overview.md`** — Explains what the dashboard is, who uses it, what each tab does, and the business context. Read this to understand *why* things are built the way they are.

2. **`Monitoring-Redesign-Tasks.md`** — The 9 tasks (Task 0–8) you will be executing. Each task has detailed instructions, files to modify, and acceptance criteria.

---

## What Already Exists

The dashboard is **already built and live**. You are not building from scratch — you are **redesigning and extending** an existing working feature.

### Live URL
`https://central.go-parts.com/usauto-monitoring`
(Task 0 renames this to `/monitoring`)

### Key Files

| File | Purpose |
|---|---|
| `app/Filament/Pages/USAutoMonitoring.php` | Main Filament page — Livewire component, all backend queries and actions |
| `resources/views/filament/pages/usauto-monitoring.blade.php` | Blade view — all HTML/Tailwind, tabs, tables, modals |
| `app/Models/OrderMonitoring.php` | Eloquent model — constants, relationships, scopes |
| `app/Models/Order.php` | Has `monitoring()` hasMany relationship |
| `app/Console/Commands/SendMonitoringMorningAlerts.php` | Scheduled morning alert emails |
| `app/Mail/MonitoringMorningAlert.php` | Mailable class |
| `resources/views/emails/monitoring-morning-alert.blade.php` | Email template |
| `config/monitoring-alerts.php` | Alert channel config (recipients, timezone) |
| `database/migrations/2026_03_03_000001_create_order_monitoring_table.php` | Already ran — table exists |

### Current Tab Structure (what exists today)
1. Live Monitor
2. Flagged
3. Issues
4. Daily Report
5. Delayed Orders

### New Tab Structure (what you're building)
1. My Queue
2. All Orders
3. Flagged
4. Issues Log
5. Director View

---

## The Codebase

- **Framework:** Laravel 10 + Filament 3 + Livewire 3
- **PHP binary:** `ea-php83` (always use this, not `php`)
- **Database:** MySQL — query via `ea-php83 artisan tinker`
- **Styling:** Tailwind CSS (dark mode first — `bg-gray-800` cards, semi-transparent badges)
- **HTTP client:** Laravel `Http` facade (used in all service classes)

### Important Patterns in USAutoMonitoring.php

**Computed properties** (Livewire) — used for all tab data:
```php
public function getLiveOrdersProperty() { ... }   // All Orders tab
public function getFlaggedOrdersProperty() { ... } // Flagged tab
public function getIssuesProperty() { ... }        // Issues tab
public function getReportStatsProperty() { ... }   // Stats widgets
public function getDailyBreakdownProperty() { ... } // Daily table
```

**Livewire actions** — used for row buttons:
```php
public function openAssignModal($monitorId) { ... }
public function assignToUser() { ... }
public function saveRemarks($monitorId) { ... }
public function markResolved($monitorId) { ... }
public function setFollowUp($monitorId, $days) { ... }
public function escalate($monitorId) { ... }
```

**Filter properties** (Livewire reactive):
```php
public string $activeTab = 'live';
public string $filterStatus = '';
public string $filterCarrierStatus = '';
public string $dateFrom = '';
public string $dateTo = '';
```

### Database Relationship (critical to understand)
```
orders
  └── orders_items          (FK: order_id)
        └── orders_items_shipments   (pivot table)
              └── shipments
```
Tracking numbers come from **both** `orders_items.tracking` and `shipments.tracking_number`.
Always use `COALESCE(s.tracking_number, oi.tracking)` in queries.

### OrderMonitoring Constants (used everywhere)
```php
// Carrier statuses
CARRIER_LABEL_CREATED = 'label_created'
CARRIER_IN_TRANSIT = 'in_transit'
CARRIER_OUT_FOR_DELIVERY = 'out_for_delivery'
CARRIER_DELIVERED = 'delivered'
CARRIER_EXCEPTION = 'exception'
CARRIER_RETURNED = 'returned'

// Monitor statuses
STATUS_MONITORING = 'monitoring'
STATUS_FLAGGED = 'flagged'
STATUS_ACTION_NEEDED = 'action_needed'
STATUS_ESCALATED = 'escalated'
STATUS_RESOLVED = 'resolved'
STATUS_CLOSED = 'closed'

// Issue type mapping (current_status / current_sub_status IDs)
ISSUE_TYPE_MAP = [
    'LIT'  => ['sub_status' => [29]],
    'RWP'  => ['sub_status' => [22]],
    'DMG'  => ['sub_status' => [23, 24]],
    'BO'   => ['sub_status' => [18, 32, 38], 'status' => [2]],
    'UNSHP'=> ['status' => [1, 3, 4]],
    'CANC' => ['status' => [7, 33, 49]],
    'PND'  => ['status' => [30, 32]],
    'OTHER'=> ['sub_status' => [31, 35]],
]

// Supplier category mapping
SUPPLIER_CATEGORIES = [
    'IN_STOCK' => ['USANV', 'USATX', 'USAIL', 'USAFL', 'USAVA'],
    'EXPRS_MI' => ['EXPRS'],
    'DEPO'     => ['DEPO-EC', 'DEPO-WC', ...],
    'TYC'      => ['TYC-EC'],
    'PBI'      => ['PBIVA'],
    'CP'       => ['KEY', 'KSI', 'MEYER', 'OCT'],
]
```

---

## Task Execution Order

```
Start immediately (parallel):
  Task 0 — Rename route to /monitoring
  Task 1 — UserFilterPreset migration + model
  Task 3 — My Queue backend queries
  Task 4 — Director View backend queries

After Task 1:
  Task 2 — Saved filter presets backend logic

After Tasks 3 + 4:
  Task 5 — Full blade view restructure  ← LARGEST TASK, critical path

After Tasks 2 + 5:
  Task 6 — Saved filter presets UI

After Task 5:
  Task 7 — Filter bar redesign

After Tasks 5 + 6 + 7:
  Task 8 — UI/UX polish
```

---

## After Every Code Change

Always run:
```bash
ea-php83 artisan view:clear
```

After adding new Filament pages or changing page registration:
```bash
ea-php83 artisan filament:clear-cached-components
ea-php83 artisan view:clear
```

After running migrations:
```bash
ea-php83 artisan migrate
```

---

## What Is NOT Being Built (out of scope for these tasks)

- **Phase 2 (Carrier Tracking Automation)** — ShipEngine API integration is on hold pending management cost approval (~$53/mo). Do not build this. The `carrier_status`, `carrier_eta`, `days_in_transit` fields in `order_monitoring` will remain null for now.
- **CSV Export** — mentioned in the original spec but not in the task list. Skip.
- **Auto-assignment rules** — mentioned in spec as "optional, can be enabled later". Skip.
- **Email CarParts template** — mentioned in spec as optional. Skip.

---

## Questions?

Read the full original implementation spec at:
`dev-documents/CarParts-Monitoring/USAuto-Monitoring-Dashboard-Plan.md`

It contains the complete database schema, all query logic explanations, issue type mappings, supplier code definitions, and the original 9-step SOP that this dashboard replaces.