Opportunity / Lead Generation
Relevant source files
The following files were used as context for generating this wiki page:
The Opportunity and Lead Generation system identifies high-intent social conversations by analyzing normalized documents from multiple platforms. It clusters related documents into single opportunities and scores them against a workspace's monitoring profile to prioritize the most relevant leads for developer community engagement.
The system transforms raw document records into evidence-backed opportunity entities through a deterministic pipeline of clustering, feature extraction, and weighted ranking. Users interact with these opportunities via a ranked queue, allowing them to review the evidence and generate grounded community contributions.
Sources: lib/opportunities/run.ts:162-175, lib/db/schema.ts:173-207
Architecture and Data Flow
The lead generation pipeline processes live evidence—documents collected within the last 7 days—to identify actionable signals. The system filters out fixture data and mocked evidence before clustering and scoring.
This diagram illustrates the sequential stages of the opportunity generation pipeline, from raw data ingestion to database persistence.
Sources: lib/opportunities/run.ts:180-205, lib/opportunities/run.ts:210-250
Document Clustering
The clusterDocuments function groups related items to prevent duplicate notifications for the same conversation thread. It uses lexical token comparison and platform matching to generate a stable clusterKey.
- It tokenizes titles and text, filtering for tokens longer than two characters.
- It identifies shared tokens across documents, requiring at least two matches for merging groups.
- If no shared tokens exist, it falls back to the first few tokens of the initial document title.
- The resulting key follows the format
platform:token1-token2.
Sources: lib/opportunities/features.ts:25-52, lib/opportunities/run.ts:104-138
Scoring Axes and Feature Extraction
Vantage evaluates each opportunity across five specific dimensions to produce a deterministic feature vector. These features allow for both automated ranking and human-readable explainability.
Sources: lib/opportunities/features.ts:54-94, lib/opportunities/types.ts:9-17
Key Feature Definitions
| Feature | Logic | Description |
|---|---|---|
| Fit | Keyword overlap | Measures match between evidence tokens and the product description/topics. |
| Intent | Intent ladder | Calculates the highest intent rung (0-4) detected across backing documents. |
| Evidence | Logarithmic scale | Measures the volume of backing documents; higher counts increase confidence. |
| Momentum | Signal growth | Combines evidence volume with the variety of platforms represented. |
| Timing | Recency decay | Scores the freshness of the latest post, decaying over a 168-hour window. |
| Sources: lib/opportunities/features.ts:65-94, app/opportunities/[id]/page.tsx:82-90 |
Feature Weights and Scoring
The system applies a baseline weight to each feature to calculate a final score between 0 and 1.
export const BASELINE_FEATURE_WEIGHTS: Record<ScoredFeatureName, number> = {
fit: 0.25,
intent: 0.3,
evidence: 0.2,
momentum: 0.15,
timing: 0.1,
};
Sources: lib/opportunities/features.ts:109-115
Opportunity Status and Routing
After computing features, the system routes the opportunity to a specific lifecycle status. This routing determines whether an item appears in the user's primary queue or requires manual review.
This flowchart defines the deterministic logic used to assign an OpportunityStatus based on computed features.
Sources: lib/opportunities/features.ts:145-152
Status Actions
| Status | Recommended Action |
|---|---|
| opportunity | Draft a grounded reply and open the original thread. |
| monitor | Watch for follow-up posts; revisit if intent rises. |
| review | Human review required due to low confidence or conflicting signals. |
| ignore | No action taken due to weak fit or low intent. |
| Sources: lib/opportunities/features.ts:154-165 |
Database Model
The Opportunity system relies on three primary tables to manage lead state and backing evidence.
Sources: lib/db/schema.ts:173-233
The ER diagram shows the relationships between workspace tenants, identified opportunities, and the specific documents acting as evidence.
opportunity Table Fields
| Field | Type | Description |
|---|---|---|
id | uuid | Unique identifier for the opportunity. |
status | enum | Current lifecycle state (review, opportunity, etc.). |
features | jsonb | Deterministic feature vector (fit, intent, evidence, etc.). |
cluster_key | text | Unique key generated from document tokens for deduplication. |
score | real | Final calculated score for ranking. |
| Sources: lib/db/schema.ts:173-207 |
Plan Enforcement and Limits
Lead generation is subject to plan-based entitlements. The buildOpportunities process consumes a scored_leads_per_day limit when creating new opportunities. If a workspace reaches its daily cap, the system reports a budget_limited coverage status instead of failing, and it continues to refresh existing opportunities without consuming additional quota.
Sources: lib/opportunities/run.ts:259-278, test/plan-enforcement.test.ts:46-60
Conclusion
The Lead Generation module ensures that users engage with high-value conversations by filtering noise and grouping related signals. By utilizing a deterministic scoring model based on Fit, Intent, Evidence, Momentum, and Timing, Vantage provides a transparent and actionable queue of community opportunities.