# LeadPilot — Master User Interaction Flows (20 Core Flows)

**Document Version:** 1.0.0 (Phase 3 UX Architecture Lock)  
**Status:** Approved & Formally Recorded  

---

## 1. Flow Index & Summary

```
+---------------------------------------------------------------------------------------------------------------+
| FLOW ID | FLOW NAME                         | TRIGGER                               | TERMINAL SUCCESS STATE  |
+---------+-----------------------------------+---------------------------------------+-------------------------+
| Flow 01 | New Workspace Onboarding          | User registration verified            | Dashboard + First Lead  |
| Flow 02 | Manual Lead Creation              | User presses 'N' or clicks '+ Lead'   | Lead saved & AI scored  |
| Flow 03 | Website Form Lead Capture         | Public website visitor submits form   | Ingested in Inbox < 1s  |
| Flow 04 | Guided CSV Bulk Import            | User uploads spreadsheet              | Batch imported & mapped |
| Flow 05 | REST API Lead Capture             | External server POSTs to `/leads`     | HTTP 201 + ID returned  |
| Flow 06 | Inbound Webhook Lead Capture      | Typeform / Webflow sends webhook      | Payload mapped to lead  |
| Flow 07 | AI Qualification & Intent Scoring | Background queue worker runs          | Score & Action updated  |
| Flow 08 | "No Lead Left Behind" Triage      | User visits Attention Hub             | Items cleared to zero   |
| Flow 09 | Rapid Lead First Response         | Rep clicks 1-click template in Detail | Contacted stage + timer |
| Flow 10 | Pipeline Drag & Advance           | Rep moves card on Kanban board        | Stage updated in DB     |
| Flow 11 | One-Time Follow-up Scheduling     | Rep clicks 'Schedule Task'            | Task placed in calendar |
| Flow 12 | Follow-up Execution & Complete    | Rep executes nudge in Follow-up Hub   | Task marked Completed   |
| Flow 13 | Staged Sequence Multi-Touch       | Cron evaluates step delays            | Nudge surfaced to rep   |
| Flow 14 | Marking a Deal as Won             | Rep drags to Won stage                | Revenue logged + confetti|
| Flow 15 | Marking a Deal as Lost            | Rep drags to Lost stage               | Lost Reason modal saved |
| Flow 16 | Team Lead Reassignment            | Manager reassigns lead owner          | Owner updated & alerted |
| Flow 17 | Embed Form Source Setup           | Admin configures website snippet      | HTML code copied        |
| Flow 18 | Workspace Profile & Working Hours | Admin updates company hours           | Settings saved to DB    |
| Flow 19 | Developer API Key Generation      | Admin generates REST token            | Plain secret copied     |
| Flow 20 | AI Provider Failure & Recovery    | OpenAI returns HTTP 500 error         | Heuristic rules applied |
+---------------------------------------------------------------------------------------------------------------+
```

---

## 2. Deep Flow Walkthroughs (Key Flows)

### Flow 08: "No Lead Left Behind" Hub Triage
```
User clicks "Needs Attention (7)" in Navigation Sidebar
                 │
                 ▼
Attention Hub opens displaying 7 urgent cards sorted by priority
                 │
                 ▼
User clicks [1-Click: Send Intro Template] on Card 1 (Rajesh Patel)
                 │
                 ▼
Modal opens with pre-populated merge text -> User clicks [Copy & Mark Sent]
                 │
                 ▼
Lead advances to 'Contacted'; Sequence Day 1 scheduled; Card 1 smoothly animates away
                 │
                 ▼
Counter decreases from 7 -> 6; user continues until "Inbox Zero" Golden Shield appears
```

### Flow 15: Marking a Deal as Lost (Protocol Flow)
```
User drags lead "Acme Corp" into the 'Lost' dropzone (or selects Lost from dropdown)
                 │
                 ▼
Mandatory Lost Reason Modal (LP-PIPE-003) opens immediately
                 │
                 ▼
User selects radio: "Price (Quote too high)" + enters optional note: "Client has $5k budget"
                 │
                 ▼
User clicks [Confirm Mark as Lost]
                 │
                 ▼
System updates DB: status='lost', pipeline_stage='lost', lost_reason='price'
                 │
                 ▼
All pending follow-ups cancelled; Activity logged; Card moves to Lost Archive
```