sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
83af32eb8879cfed455179fcd4059cd7fa52745a
orion/app/modules/prospecting/docs/user-journeys.md
Samir Boulahtit f141cc4e6a docs: migrate module documentation to single source of truth 
Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 23:38:37 +01:00

436 lines
20 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink