Lead Pipelines Overview & Lifecycle
At the financial and operational core of veridex-hitech-web-application is an automated, resilient Lead Ingestion Clearinghouse. The engine ingests, validates, normalizes, sanitizes, persists, and forwards insurance quote inquiries from five distinct acquisition channels directly to licensed agency underwriters and downstream CRM platforms.
1. Multi-Channel Lead Ingestion Topology
2. Ingestion Channels & Capabilities
| Channel | Entry Point | Authentication & Security | Destination Model | Downstream CRM Forwarding |
|---|---|---|---|---|
| Direct Web Quote | Modal / /get-quote | reCAPTCHA v3/v2 + FORM_SUBMISSION limit | Lead | Yes (Truck & Business lines automatically) |
| Partner Ingestion | /api/leads/* | x-hti-signature HMAC-SHA256 + 5-min timestamp | HtiLead | Stored as authoritative; already synced with Falcon |
| Meta Lead Ads | /api/webhooks/meta | hub.verify_token + X-Hub-Signature-256 | MetaLead | Follow-up queue in Admin Control Center |
| Google Ads Leads | /api/webhook/google | X-Goog-Signature secret verification | GoogleWebhookLog | Normalized lead review |
| Field Marketing QR | /e/:slug | Dynamic form schema + licensed agent attribution | EventLead | Attributed to campaign and licensed agent |
| Customer Resumption | /dashboard | Session cookie (authjs.session-token) | Lead (status transition: draft -> completed) | Dispatches to CRM on complete |
3. Lead Lifecycle State Transitions
Every lead moves through defined lifecycle states, tracked across database models and dashboard views:
4. Architectural Guarantees & SLAs
- Zero Lead Loss: The platform treats lead payloads as mission-critical financial assets. Every HTTP POST payload is persisted to MongoDB before any downstream network dispatch is initiated.
- Payload Preservation: Inbound partner payloads delivered via
/api/leads/*preserve 100% of vendor-specific JSON fields insideHtiLead.leadandHtiLead.rawPayload. No nested attributes are dropped during schema normalization. - Sub-Second Response Latency: Downstream CRM synchronization (
sendLeadToHtiCrm) executes asynchronously as a non-blocking background task. The web visitor receives an instant HTTP 200/201 response within 120ms without waiting for third-party CRM network roundtrips. - Idempotent Upsert: If an inbound partner lead specifies an existing external identifier (
lead.id), the system updates the existing document in place rather than generating duplicate entries.