Lead Review Queue
Relevant source files
The following files were used as context for generating this wiki page:
The Lead Review Queue manages individual high-intent social signals identified by the Vantage pipeline. It allows users to evaluate scored leads, verify the intent behind collected documents, and initiate the drafting process for community engagement. The system filters raw social media documents into actionable leads based on intent rungs and confidence scores.
Sources: app/review/page.tsx:1-87, README.md
System Architecture
The review system operates on a pipeline that transforms raw documents into scored leads. Data flows from collectors through a normalization and classification stage before appearing in the queue.
Data Flow Diagram
The following diagram illustrates how a social media post becomes an actionable item in the review queue.
Data Models
The review queue relies on the relationship between document records and lead records. A document represents the raw content, while a lead represents the metadata associated with the intent analysis.
The Lead Entity
The lead table stores the results of the pipeline's analysis, including scoring and classification.
| Field | Type | Description |
|---|---|---|
id | uuid | Primary identifier for the lead. |
intentRung | integer | The level of intent identified (e.g., asking for a solution). |
confidence | real | The model's confidence in the classification (0.0 to 1.0). |
score | real | The overall ranking score for the lead. |
status | enum | The current lifecycle state (new, reviewing, approved, etc). |
reason | text | The natural language explanation for why this lead was flagged. |
Sources: lib/db/schema.ts:168-185
Relationship Schema
Sources: lib/db/schema.ts:90-264
Pipeline Integration
The queue is populated by the runPipeline function. This function selects collected documents that do not yet have associated leads and processes them through an intent ladder.
- Selection: Fetches documents for a specific
workspaceIdordered by collection date. - Filtering: Excludes documents that already possess an entry in the
leadtable. - Classification: Invokes
classifyIntentto determine theintentRungandfactors. - Insertion: Creates a new
leadrecord if the classification meets the workspace's threshold.
Sources: lib/pipeline/run.ts:9-45
Lead Lifecycle and Statuses
Leads progress through several states as they are processed by the user. The queue UI primarily focuses on leads with new, queued, or reviewing statuses.
| Status | Definition |
|---|---|
new | Recently created lead not yet seen by a user. |
reviewing | User has opened the lead detail or started a draft. |
approved | The intent is verified and a contribution is planned. |
rejected | User determined the lead is not relevant or useful. |
posted | A contribution has been successfully handoff/posted to the source. |
Sources: lib/db/schema.ts:68-76, lib/pipeline/run.ts:68-73
Lead Review Interface
The review page (/review) provides a high-level list of leads for a specific workspace. It displays the primary content of the document alongside its scoring metrics.
- Metric Visibility: Displays
intentRung,score, andconfidencefor every item. - Platform Attribution: Identifies the source platform (e.g., GitHub, Reddit, HN).
- Contextual Reasoning: Shows the
reasongenerated by the classification model to explain the lead's relevance. - Safe Links: Uses the
SafeLinkcomponent to navigate to the originalurlCanonicalof the document.
Sources: app/review/page.tsx:55-87
Lead Retrieval Logic
The listReviewQueue function retrieves data for the UI using an inner join between the lead and document tables.
// lib/pipeline/run.ts:60-77
export async function listReviewQueue(workspaceId: string, limit = 50) {
const db = getDb();
return db
.select({
lead,
document,
})
.from(lead)
.innerJoin(document, eq(document.id, lead.documentId))
.where(
and(
eq(lead.workspaceId, workspaceId),
inArray(lead.status, ["new", "queued", "reviewing"]),
),
)
.orderBy(desc(lead.score), desc(lead.createdAt))
.limit(limit);
}
Contribution Drafting
When a user selects a lead for action, the system moves into the drafting phase. This involves generating a grounded contribution based on evidence retrieved from the documents.
Drafting Constraints
The system enforces strict rules during the review of drafts:
- Prohibition Check: If the venue (like Stack Overflow) prohibits AI-generated text, only a "Research Brief" is permitted.
- Factual Grounding: Every factual statement in a draft must have a corresponding
claimlinked to adocumentIdand a specificquote. - Human Verification: Users must check
rulesReviewedandfactsReviewedbefore a draft can be approved for handoff.
Sources: lib/drafting/contribution.ts:51-85, app/opportunities/[id]/draft-panel.tsx:162-212
Draft Handoff Flow
Summary
The Lead Review Queue acts as the central hub for human-in-the-loop verification of social signals. By combining automated intent classification with a structured review and drafting interface, it ensures that only high-quality, evidence-backed contributions are prepared for community engagement. The system prioritizes technical accuracy by requiring specific citations for all AI-generated claims.