# Prospecting Module - User Journeys

## Personas

| # | Persona | Role / Auth | Description |
|---|---------|-------------|-------------|
| 1 | **Platform Admin** | `admin` role | Manages prospects, runs enrichment scans, sends campaigns, exports leads |

!!! note "Admin-only module"
    The prospecting module is exclusively for platform admins. There are no store-level
    or customer-facing pages. All access requires admin authentication.

---

## Platforms Using Prospecting

The prospecting module is enabled on multiple platforms:

| Platform | Domain | Path Prefix (dev) |
|----------|--------|--------------------|
| HostWizard | hostwizard.lu | `/platforms/hosting/` |

---

## Dev URLs (localhost:9999)

The dev server uses path-based platform routing: `http://localhost:9999/platforms/hosting/...`

### 1. Admin Pages

Login as: `admin@orion.lu` or `samir.boulahtit@gmail.com`

| Page | Dev URL |
|------|---------|
| Dashboard | `http://localhost:9999/platforms/hosting/admin/prospecting` |
| Prospects List | `http://localhost:9999/platforms/hosting/admin/prospecting/prospects` |
| Prospect Detail | `http://localhost:9999/platforms/hosting/admin/prospecting/prospects/{prospect_id}` |
| Leads List | `http://localhost:9999/platforms/hosting/admin/prospecting/leads` |
| Quick Capture | `http://localhost:9999/platforms/hosting/admin/prospecting/capture` |
| Scan Jobs | `http://localhost:9999/platforms/hosting/admin/prospecting/scan-jobs` |
| Campaigns | `http://localhost:9999/platforms/hosting/admin/prospecting/campaigns` |

### 2. Admin API Endpoints

**Prospects** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| GET | prospects | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects` |
| GET | prospect detail | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}` |
| POST | create prospect | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects` |
| PUT | update prospect | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}` |
| DELETE | delete prospect | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}` |
| POST | import CSV | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/import` |

**Leads** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| GET | leads (filtered) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/leads` |
| GET | top priority | `http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/top-priority` |
| GET | quick wins | `http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/quick-wins` |
| GET | export CSV | `http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/export/csv` |

**Enrichment** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| POST | HTTP check (single) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/http-check/{id}` |
| POST | HTTP check (batch) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/http-check/batch` |
| POST | tech scan (single) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/tech-scan/{id}` |
| POST | tech scan (batch) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/tech-scan/batch` |
| POST | performance (single) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/performance/{id}` |
| POST | performance (batch) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/performance/batch` |
| POST | contacts (single) | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/contacts/{id}` |
| POST | full enrichment | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/full/{id}` |
| POST | score compute | `http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/score-compute/batch` |

**Interactions** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| GET | prospect interactions | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}/interactions` |
| POST | log interaction | `http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}/interactions` |
| GET | upcoming follow-ups | `http://localhost:9999/platforms/hosting/api/admin/prospecting/interactions/upcoming` |

**Campaigns** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| GET | list templates | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/templates` |
| POST | create template | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/templates` |
| PUT | update template | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/templates/{id}` |
| DELETE | delete template | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/templates/{id}` |
| POST | preview campaign | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/preview` |
| POST | send campaign | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/send` |
| GET | list sends | `http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/sends` |

**Stats** (prefix: `/platforms/hosting/api/admin/prospecting/`):

| Method | Endpoint | Dev URL |
|--------|----------|---------|
| GET | dashboard stats | `http://localhost:9999/platforms/hosting/api/admin/prospecting/stats` |
| GET | scan jobs | `http://localhost:9999/platforms/hosting/api/admin/prospecting/stats/jobs` |

---

## Production URLs (hostwizard.lu)

In production, the platform uses **domain-based routing**.

### Admin Pages & API

| Page / Endpoint | Production URL |
|-----------------|----------------|
| Dashboard | `https://hostwizard.lu/admin/prospecting` |
| Prospects | `https://hostwizard.lu/admin/prospecting/prospects` |
| Prospect Detail | `https://hostwizard.lu/admin/prospecting/prospects/{id}` |
| Leads | `https://hostwizard.lu/admin/prospecting/leads` |
| Quick Capture | `https://hostwizard.lu/admin/prospecting/capture` |
| Scan Jobs | `https://hostwizard.lu/admin/prospecting/scan-jobs` |
| Campaigns | `https://hostwizard.lu/admin/prospecting/campaigns` |
| API - Prospects | `GET https://hostwizard.lu/api/admin/prospecting/prospects` |
| API - Leads | `GET https://hostwizard.lu/api/admin/prospecting/leads` |
| API - Stats | `GET https://hostwizard.lu/api/admin/prospecting/stats` |

---

## Data Model

### Prospect

```
Prospect
├── id (PK)
├── channel: DIGITAL | OFFLINE
├── business_name (str)
├── domain_name (str, unique)
├── status: PENDING | ACTIVE | INACTIVE | PARKED | ERROR | CONTACTED | CONVERTED
├── source (str)
├── Digital fields: has_website, uses_https, http_status_code, redirect_url, scan timestamps
├── Offline fields: address, city, postal_code, country, location_lat/lng, captured_by_user_id
├── notes, tags (JSON)
├── created_at, updated_at
└── Relationships: tech_profile, performance_profile, score, contacts, interactions
```

### Prospect Score (0-100)

```
ProspectScore
├── score (0-100, overall)
├── Components: technical_health (max 40), modernity (max 25), business_value (max 25), engagement (max 10)
├── reason_flags (JSON array)
├── score_breakdown (JSON dict)
└── lead_tier: top_priority | quick_win | strategic | low_priority
```

### Status Flow

```
PENDING
  ↓ (HTTP check determines website status)
ACTIVE (has website) or PARKED (no website / parked domain)
  ↓ (contact attempt)
CONTACTED
  ↓ (outcome)
CONVERTED (sale) or INACTIVE (not interested)

Alternative: PENDING → ERROR (invalid domain, technical issues)
```

---

## User Journeys

### Journey 1: Digital Lead Discovery (Domain Scanning)

**Persona:** Platform Admin
**Goal:** Import `.lu` domains, enrich them, and identify sales opportunities

```mermaid
flowchart TD
    A[Import CSV of .lu domains] --> B[Prospects created with status PENDING]
    B --> C[Run HTTP check batch]
    C --> D[Run tech scan batch]
    D --> E[Run performance scan batch]
    E --> F[Run contact scrape]
    F --> G[Compute scores batch]
    G --> H[View scored leads]
    H --> I{Score tier?}
    I -->|>= 70: Top Priority| J[Export & contact immediately]
    I -->|50-69: Quick Win| K[Queue for campaign]
    I -->|30-49: Strategic| L[Monitor & nurture]
    I -->|< 30: Low Priority| M[Deprioritize]
```

**Steps:**

1. Navigate to Dashboard:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting`
    - Prod: `https://hostwizard.lu/admin/prospecting`
2. Import domains via CSV:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/import`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/prospects/import`
3. Run HTTP batch check:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/http-check/batch`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/http-check/batch`
4. Run tech scan batch:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/tech-scan/batch`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/tech-scan/batch`
5. Run performance scan batch:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/performance/batch`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/performance/batch`
6. Compute scores:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/score-compute/batch`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/score-compute/batch`
7. Monitor scan jobs:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/scan-jobs`
    - Prod: `https://hostwizard.lu/admin/prospecting/scan-jobs`
8. View scored leads:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/leads`
    - Prod: `https://hostwizard.lu/admin/prospecting/leads`
9. Export top priority leads:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/export/csv?min_score=70`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/leads/export/csv?min_score=70`

---

### Journey 2: Offline Lead Capture

**Persona:** Platform Admin (out in the field)
**Goal:** Capture business details from in-person encounters using the mobile-friendly capture form

```mermaid
flowchart TD
    A[Meet business owner in-person] --> B[Open Quick Capture on mobile]
    B --> C[Enter business name, address, contact info]
    C --> D[Prospect created with channel=OFFLINE]
    D --> E{Has website?}
    E -->|Yes| F[Run full enrichment]
    E -->|No| G[Score based on business value only]
    F --> H[Prospect fully enriched with score]
    G --> H
    H --> I[Log interaction: VISIT]
    I --> J[Set follow-up date]
```

**Steps:**

1. Open Quick Capture (mobile-friendly):
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/capture`
    - Prod: `https://hostwizard.lu/admin/prospecting/capture`
2. Fill in business details and submit:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/prospects`
    - Body includes: `channel: "offline"`, `business_name`, `address`, `city`, `postal_code`
3. Optionally run full enrichment (if domain known):
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/full/{id}`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/full/{id}`
4. Log the interaction:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}/interactions`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/prospects/{id}/interactions`
    - Body: `{ "interaction_type": "visit", "notes": "Met at trade fair", "next_action": "Send proposal", "next_action_date": "2026-03-10" }`

---

### Journey 3: Lead Qualification & Export

**Persona:** Platform Admin
**Goal:** Filter enriched prospects by score tier and export qualified leads for outreach

```mermaid
flowchart TD
    A[Navigate to Leads page] --> B[Filter by score tier]
    B --> C{View preset lists}
    C -->|Top Priority| D[Score >= 70]
    C -->|Quick Wins| E[Score 50-69]
    C -->|Custom filter| F[Set min/max score, channel, contact type]
    D --> G[Review leads]
    E --> G
    F --> G
    G --> H[Export as CSV]
    H --> I[Use in campaigns or CRM]
```

**Steps:**

1. Navigate to Leads:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/leads`
    - Prod: `https://hostwizard.lu/admin/prospecting/leads`
2. View top priority leads:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/top-priority`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/leads/top-priority`
3. View quick wins:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/quick-wins`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/leads/quick-wins`
4. Filter with custom parameters:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/leads?min_score=60&has_email=true&channel=digital`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/leads?min_score=60&has_email=true&channel=digital`
5. Export filtered leads as CSV:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/leads/export/csv?min_score=50&lead_tier=quick_win`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/leads/export/csv?min_score=50&lead_tier=quick_win`

---

### Journey 4: Campaign Creation & Outreach

**Persona:** Platform Admin
**Goal:** Create email campaign templates and send targeted outreach to qualified prospects

```mermaid
flowchart TD
    A[Navigate to Campaigns] --> B[Create campaign template]
    B --> C[Choose lead type: no_website, bad_website, etc.]
    C --> D[Write email template with variables]
    D --> E[Preview rendered for specific prospect]
    E --> F{Looks good?}
    F -->|Yes| G[Select qualifying leads]
    G --> H[Send campaign]
    H --> I[Monitor send status]
    F -->|No| J[Edit template]
    J --> E
```

**Steps:**

1. Navigate to Campaigns:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/campaigns`
    - Prod: `https://hostwizard.lu/admin/prospecting/campaigns`
2. Create a campaign template:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/templates`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/campaigns/templates`
    - Body: `{ "name": "No Website Outreach", "lead_type": "no_website", "channel": "email", "language": "fr", "subject_template": "Votre presence en ligne", "body_template": "Bonjour {{business_name}}..." }`
3. Preview the template for a specific prospect:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/preview`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/campaigns/preview`
    - Body: `{ "template_id": 1, "prospect_id": 42 }`
4. Send campaign to selected prospects:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/send`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/campaigns/send`
    - Body: `{ "template_id": 1, "prospect_ids": [42, 43, 44] }`
5. Monitor campaign sends:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/campaigns/sends`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/campaigns/sends`

---

### Journey 5: Interaction Tracking & Follow-ups

**Persona:** Platform Admin
**Goal:** Log interactions with prospects and track follow-up actions

```mermaid
flowchart TD
    A[Open prospect detail] --> B[View interaction history]
    B --> C[Log new interaction]
    C --> D[Set next action & date]
    D --> E[View upcoming follow-ups]
    E --> F[Complete follow-up]
    F --> G{Positive outcome?}
    G -->|Yes| H[Mark as CONTACTED → CONVERTED]
    G -->|No| I[Schedule next follow-up or mark INACTIVE]
```

**Steps:**

1. View prospect detail:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/prospects/{id}`
    - Prod: `https://hostwizard.lu/admin/prospecting/prospects/{id}`
2. View interactions:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}/interactions`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/prospects/{id}/interactions`
3. Log a new interaction:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/prospects/{id}/interactions`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/prospects/{id}/interactions`
    - Body: `{ "interaction_type": "call", "subject": "Follow-up call", "outcome": "positive", "next_action": "Send proposal", "next_action_date": "2026-03-15" }`
4. View upcoming follow-ups across all prospects:
    - API Dev: `GET http://localhost:9999/platforms/hosting/api/admin/prospecting/interactions/upcoming`
    - API Prod: `GET https://hostwizard.lu/api/admin/prospecting/interactions/upcoming`

---

### Journey 6: Full Enrichment Pipeline (Single Prospect)

**Persona:** Platform Admin
**Goal:** Run the complete enrichment pipeline for a single prospect to get all data at once

```mermaid
flowchart TD
    A[Open prospect detail] --> B[Click 'Full Enrichment']
    B --> C[Step 1: HTTP check]
    C --> D{Has website?}
    D -->|Yes| E[Step 2: Tech scan]
    D -->|No| H[Step 5: Compute score]
    E --> F[Step 3: Performance audit]
    F --> G[Step 4: Contact scrape]
    G --> H
    H --> I[Prospect fully enriched]
    I --> J[View score & breakdown]
```

**Steps:**

1. Run full enrichment for a prospect:
    - API Dev: `POST http://localhost:9999/platforms/hosting/api/admin/prospecting/enrichment/full/{prospect_id}`
    - API Prod: `POST https://hostwizard.lu/api/admin/prospecting/enrichment/full/{prospect_id}`
2. View the enriched prospect detail:
    - Dev: `http://localhost:9999/platforms/hosting/admin/prospecting/prospects/{prospect_id}`
    - Prod: `https://hostwizard.lu/admin/prospecting/prospects/{prospect_id}`

The full enrichment runs 5 sequential steps:

1. **HTTP check** — Verifies domain connectivity, checks HTTPS, records redirects
2. **Tech scan** — Detects CMS, server, hosting provider, JS framework, SSL cert details
3. **Performance audit** — Runs PageSpeed analysis, records load times and scores
4. **Contact scrape** — Extracts emails, phones, addresses, social links from the website
5. **Score compute** — Calculates 0-100 opportunity score with component breakdown

---

## Recommended Test Order

1. **Journey 1** (steps 1-3) - Import domains and run HTTP checks first
2. **Journey 6** - Run full enrichment on a single prospect to test the complete pipeline
3. **Journey 1** (steps 4-9) - Run batch scans and view scored leads
4. **Journey 2** - Test offline capture on mobile
5. **Journey 3** - Filter and export leads
6. **Journey 4** - Create campaign templates and send to prospects
7. **Journey 5** - Log interactions and check follow-ups

!!! tip "Enrichment order matters"
    The enrichment pipeline must run in order: HTTP check first (determines if website exists),
    then tech scan, performance, and contacts (all require a live website). Score computation
    should run last as it uses data from all other steps.