Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Vantage is a social listening and lead capture platform designed to identify high-intent conversations across platforms like Reddit, Hacker News, and X (Twitter). The system ingests external data, normalizes it into documents, and applies a multi-stage pipeline to score these documents as potential business opportunities. Users can then generate grounded, evidence-backed contribution drafts for these conversations.
Sources: README.md:1-5, app/page.tsx:28-32
System Stack and Deployment
The project utilizes a modern TypeScript stack optimized for edge deployment:
- Framework: Next.js (App Router) with React 19.
- Database: Neon Postgres interfaced via Drizzle ORM.
- Authentication: Neon Auth (Managed Better Auth).
- Runtime: Cloudflare Workers via
@opennextjs/cloudflare. - Package Management: pnpm.
Sources: package.json:1-55, README.md:7-13
Cloudflare Workers Infrastructure
Vantage runs as a Cloudflare Worker. The deployment process uses @opennextjs/cloudflare to bundle the Next.js application into a worker entry point. A scheduled handler in worker-entry.mjs triggers periodic collector runs via a service binding to the tick route, secured by a CRON_SECRET.
Sources: README.md:92-95, README.md:139-145
Data Model
The persistence layer is structured to support multi-tenant workspaces with isolated monitoring profiles and leads.
Core Entities
| Table | Description |
|---|---|
workspace | The primary tenant unit, containing plans, budgets, and owner information. |
monitoring_profile | Defines the product description, target customers, and topics for a workspace. |
source | External feed configurations (e.g., RSS, HN) with polling state (etag, cursor). |
document | Normalized content collected from sources. |
lead | A single document scored for intent and relevance. |
opportunity | A cluster of related documents representing a high-level lead. |
opportunity_draft | AI-generated or user-edited responses grounded in opportunity evidence. |
Sources: lib/db/schema.ts:89-280, README.md:25-32
Entity Relationships
The following diagram illustrates the relationship between core data entities.
The system uses UUIDs for primary keys and establishes foreign key constraints with ON DELETE CASCADE for tenant isolation.
Sources: lib/db/schema.ts:89-280, drizzle/0000_m1_core.sql:1-68
Collector Pipeline
The collection system retrieves raw data from various social and technical platforms using a prioritized list of providers.
Collection Logic
- Poll Trigger: A cron job (
/api/cron/tick) runs every 3 hours. - Provider Selection: The system prefers structured APIs (Scavio) over browser-based scraping.
- Normalization: Raw data is converted into
documentrecords with a uniquecontent_hash.
Sources: README.md:34-60, README.md:139-140
Scrape Providers Priority
- YouTube: Scavio comments -> TinyFish Fetch/Search -> YouTube Data API -> Fixture.
- Reddit/X: Scavio search client.
- Product Hunt: TinyFish Search+Fetch -> PH GraphQL -> Fixture.
Sources: README.md:46-56
Opportunity Scoring and Ranking
Vantage calculates five specific scores to determine if a conversation is worth joining.
The Five Scores
| Score | Logic |
|---|---|
| Fit | Matches the poster's problem against the monitoring_profile product description. |
| Intent | Detects if the user is actively seeking a solution versus venting. |
| Evidence | Weighted by the number of posts and sources backing the opportunity cluster. |
| Momentum | Measures conversation growth and reply velocity. |
| Timing | Prioritizes recent posts so replies remain relevant. |
Sources: app/page.tsx:81-85, test/opportunity-queue.test.ts:77-85, app/opportunities/[id]/page.tsx:64-70
Feature Computation Flow
Contribution Drafting System
The drafting system generates grounded responses using LLMs, ensuring every claim is backed by the collected evidence.
Model Routing and Triage
The system performs a two-stage LLM process if INCO_TRIAGE_ENABLED is set:
- Triage: Uses a cheaper model (e.g.,
deepseek-v4.1-flash) to decide if a conversation warrants a reply. - Generation: Uses a premium model (e.g.,
openai/gpt-6.1-solorclaude-sonnet-5.5) to write the draft.
Sources: lib/drafting/contribution.ts:88-105, test/contribution-model-routing.test.ts:36-46
Grounded Drafting Requirements
To maintain quality and prevent "hallucinations," the system enforces strict validation rules:
- No Promotion: Drafts must not include CTAs like "buy now" or "book a demo".
- Exact Quotes: Every factual statement in a draft must map to an exact quote found in the
documentcontent. - Rule Compliance: The system checks
contributionRulefor venue-specific prohibitions (e.g., Hacker News or Stack Overflow might prohibit AI text). - Human Review: Users must verify facts and rules before the draft is marked as
approvedAt.
Sources: lib/drafting/contribution.ts:41-75, app/opportunities/[id]/draft-panel.tsx:160-185, test/draft-handoff.test.ts:83-88
Browser Runtime (Headless Scraper)
For sources that require browser execution, Vantage uses a Cloudflare Browser Rendering binding.
Security and Resource Management
- SSRF Protection: The
isDeniedHostutility blocks requests to internal network addresses and major social platforms (to prevent bot detection). - Cost Tracking: Each browser run records a
cost_eventbased on milliseconds used (X-Browser-Ms-Usedheader). - Wall Time Fallback: If the browser header is missing, the system falls back to wall-clock time for billing.
Sources: test/browser-run.test.ts:54-95, lib/db/schema.ts:391-410
Summary
The Vantage architecture provides a robust pipeline from raw social data to actionable business leads. By combining a multi-tenant Postgres schema with edge-ready Cloudflare Workers and a multi-stage LLM drafting system, it enables scalable, evidence-based social listening. The system prioritizes data integrity through strict quote validation and maintains operational control via granular source switches and cost tracking.
Sources: README.md:1-5, lib/db/schema.ts:1-20