sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
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

20 KiB
Raw Permalink 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

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

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

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

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

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

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