Introduction to Vantage
Relevant source files
The following files were used as context for generating this wiki page:
Vantage is a social listening and lead capture platform. It scans platforms like Reddit, Hacker News, and X for conversations relevant to a user's product. The system identifies potential leads by matching user-defined monitoring profiles against collected documents.
The platform provides a ranked list of opportunities based on intent and relevance. It allows users to draft grounded replies using AI models while ensuring all claims match verified evidence. Vantage prioritizes research and manual posting over automated bot behavior.
Sources: README.md:1-12, app/page.tsx:28-36
Core Pipeline and Data Flow
The Vantage pipeline moves data from external social feeds into a normalized database and finally into ranked opportunities. The system executes this flow through scheduled cron jobs or manual API triggers.
Pipeline Stages
- Collection: Workers fetch data from sources like HN, RSS, and Reddit.
- Normalization: The system converts raw data into a standard
documentformat. - Scoring: An intent ladder analyzes documents to identify potential leads.
- Clustering: Related documents group together into shared
opportunityrecords. - Drafting: The system generates suggested replies based on product material and evidence.
Sources: README.md:46-60, lib/db/schema.ts:145-200
System Architecture Diagram
The following diagram illustrates the flow from data acquisition to opportunity generation.
The diagram shows how raw external data is processed and stored before reaching the end user.
Sources: README.md:46-64, lib/db/schema.ts:168-226
Data Model
Vantage uses a multi-tenant schema based on workspaces. Each workspace maintains its own sources, documents, and monitoring profiles.
Primary Database Tables
| Table | Purpose | Key Fields |
|---|---|---|
workspace | Defines the tenant and plan limits. | id, name, plan, budget_usd_month |
source | Configures external feeds and poll status. | type, lane, config, health, cursor |
document | Stores normalized content from sources. | url_canonical, platform, content_md, content_hash |
lead | Tracks documents scored as potential matches. | intent_rung, confidence, score, status |
opportunity | Clusters multiple evidence documents. | title, summary, features, cluster_key |
Sources: README.md:38-44, lib/db/schema.ts:108-250
Entity Relationship Structure
The following diagram shows how documents relate to leads and clustered opportunities.
The diagram shows that opportunities are aggregate entities backed by one or more evidence documents.
Sources: lib/db/schema.ts:133-270
Opportunity Scoring
Vantage evaluates opportunities using five deterministic feature scores. These scores determine if a conversation is worth joining.
Scoring Metrics
- Fit: Measures how closely the poster's problem matches the product description.
- Intent: Determines if the user is seeking a solution or just venting.
- Evidence: Counts the number of posts and sources backing the opportunity.
- Momentum: Tracks if the conversation is actively growing.
- Timing: Evaluates the recency of the post to ensure a timely reply.
Sources: app/page.tsx:86-105, test/opportunity-queue.test.ts:77-88
Status Decisions
Based on features, the system assigns one of four statuses:
- Opportunity: High-confidence match for immediate action.
- Review: Weak signal requiring human verification.
- Monitor: Relevant but low urgency or intent.
- Ignore: Irrelevant chatter or URL fragments.
Sources: lib/db/schema.ts:98-105, test/opportunity-queue.test.ts:25-30
Drafting and Contribution System
The drafting system generates replies grounded in verified evidence. It uses AI models to assist users while enforcing strict quality and factual rules.
Drafting Logic
Vantage fetches product material (docs, landing pages) and uses it to ground AI suggestions. The system identifies specific claims and requires each factual statement to have a matching evidence quote from a collected document.
Sources: lib/drafting/contribution.ts:40-65, test/profile-onboarding.test.ts:80-95
Sequence of Draft Generation
The sequence ensures that AI-generated text is checked against source documents before the user sees it.
Sources: lib/drafting/contribution.ts:100-125, app/opportunities/[id]/draft-panel.tsx:80-110
Contribution Rules
Vantage prohibits AI-written contributions for specific venues like Hacker News or Stack Overflow to comply with community policies. In these cases, the system provides a "Research Brief" instead of a draft.
Sources: lib/drafting/contribution.ts:130-135, test/social-provider-routing.test.ts:105-115
Infrastructure and Deployment
Vantage runs on Cloudflare Workers using the Next.js App Router. It utilizes Neon Postgres for data storage and Neon Auth for identity management.
Deployment Environment
- Runtime: Cloudflare Workers via
@opennextjs/cloudflare. - Database: Neon Postgres (Managed).
- Auth: Managed Better Auth via Neon.
- Cron: Vercel/Cloudflare crons trigger the pipeline every 3 hours.
Sources: README.md:14-25, README.md:105-115
Vantage serves as a focused tool for founders to join meaningful conversations without the noise of automated spam. By ranking intent and grounding drafts in evidence, it maintains high quality in social interactions.