# LeadPilot Dashboard — No Lead Left Behind

**Document Version:** 1.0.0 (Phase 10)  
**Status:** Implemented, Tested & Verified

---

## 1. Purpose

The LeadPilot Dashboard is the primary operational view for the product.

Its job is to immediately answer the question:

> **Which leads need my attention right now?**

The dashboard is not a vanity metrics page. Every number it shows connects directly to an action the user can take.

---

## 2. Dashboard Structure

```
PAGE HEADER
─────────────────────────────────────────────
Good morning, [Name].
7 leads need attention.

[Period Selector] [+ New Lead]

─────────────────────────────────────────────
KPI STRIP (6 primary metrics)
─────────────────────────────────────────────
New Leads | Needs Response | Follow-ups Due
Hot Leads | Won | Automation Failed

─────────────────────────────────────────────
SECONDARY KPIs
─────────────────────────────────────────────
Conversion Rate | Revenue Attributed | Recovered Leads | Lost Leads

─────────────────────────────────────────────
ATTENTION CENTER
─────────────────────────────────────────────
Critical → High → Medium items
[Send Follow-up] [Respond Now] [Open Lead]

─────────────────────────────────────────────
PIPELINE SNAPSHOT (left)  |  RECENT ACTIVITY (right)
─────────────────────────────────────────────
New         24            |  Lead created
Contacted   18            |  Stage changed
Qualified   11            |  Follow-up sent
Proposal     6            |  Automation failed
Won          4            |  ...
Lost         3            |
```

---

## 3. Period Support

| Period   | Behaviour                         |
|----------|-----------------------------------|
| `today`  | From midnight in workspace timezone |
| `7days`  | Last 7 days                       |
| `30days` | Last 30 days (default)            |

All timestamps stored in UTC. Period boundaries converted to UTC using the workspace timezone before comparison.

---

## 4. Greeting Logic

| Hour        | Greeting          |
|-------------|-------------------|
| 00:00–11:59 | Good morning      |
| 12:00–16:59 | Good afternoon    |
| 17:00–23:59 | Good evening      |

---

## 5. Empty States

### All Clear

When no attention items exist:

> ✅ You're all caught up! No leads need attention right now.

This is displayed as a success state (green card), not a dead page.

### No Pipeline Stages

> No pipeline stages found. Set up your pipeline to begin tracking leads.

### No Recent Activity

> No activity yet. Create your first lead to get started. → Add a lead

---

## 6. Error Handling

Each dashboard section is wrapped in a `try/catch`. If one section fails:
- The error is logged to `storage/logs/laravel.log`
- The failing section returns an empty default state
- All other sections continue rendering normally
- No stack traces are exposed to the UI