Opportunity Details & Draft Panel
Relevant source files
The following files were used as context for generating this wiki page:
The Opportunity Details system displays deep analysis and evidence for specific market signals discovered by Vantage. It integrates a collaborative drafting environment where users review AI-generated responses grounded in conversation evidence before handing them off to external platforms.
Sources: app/opportunities/[id]/page.tsx, lib/opportunities/run.ts
Opportunity Overview
The Opportunity Details page serves as the primary view for evaluating a clustered set of evidence. It displays qualitative analysis, quantitative scoring, and raw source material to help you decide if an intervention is warranted.
Core Components
- Analysis Section: Presents "Why it matters", "Why now", and a "Recommended next step" derived from the opportunity features.
- Score Glyph: A visual representation of the five scoring axes (Fit, Intent, Evidence, Momentum, and Timing).
- Evidence List: Displays quotes, source platforms, and timestamps for every document supporting the opportunity.
- Draft Panel: A managed environment for preparing a contribution or a research brief.
Sources: app/opportunities/[id]/page.tsx:66-140, lib/opportunities/run.ts:252-300
Scoring Axes Summary
| Axis | Description |
|---|---|
| Fit | How closely the problem matches the defined product profile. |
| Intent | The strength of the user's desire for a solution or action. |
| Evidence | The volume and quality of posts backing the opportunity. |
| Momentum | The growth and activity level of the conversation. |
| Timing | The recency of the posts to ensure a reply is still relevant. |
Sources: app/opportunities/[id]/page.tsx:103-112, lib/opportunities/run.ts:108-140
Draft Panel Architecture
The Draft Panel is a client-side component that manages the lifecycle of a draft response. It coordinates between the UI state, the drafting API, and browser capabilities like the clipboard.
Draft Lifecycle Flow
The following diagram illustrates the transition from an opportunity evidence item to a finalized handoff.
The diagram shows the sequential steps a user takes to move from selecting a conversation to copying a verified response.
Sources: app/opportunities/[id]/draft-panel.tsx:39-165
Implementation Details
- Concurrency Control: The component uses a
requestRevisionref to ignore stale fetch results when the user rapidly switches target evidence. - Target Scoping: Drafts are scoped to a specific
targetDocumentId(a UUID) to ensure citations and context remain accurate to the specific thread being joined. - Research Briefs: If a platform prohibits AI text (e.g., Hacker News) or the evidence is "discovery only", the system generates a research brief for reference instead of a postable draft.
Sources: app/opportunities/[id]/draft-panel.tsx:50-80, lib/drafting/contribution.ts:80-95, lib/drafting/repository.ts:110-130
Drafting Logic and Validation
The drafting system enforces strict grounding to prevent "hallucinations" or unsupported claims.
Grounding Requirements
Every draft must pass the validateContribution check, which enforces the following:
- Lexical Matching: Every complete factual statement must have a matching claim in the
claimsledger. - Quote Verification: Every claim must include an exact quote found within the provided evidence.
- Anti-Promotion: The system flags and rejects text containing common promotional phrases, CTAs, or invented personal experience.
- Repeat Detection: Drafts are compared against
existingRepliesin the thread to ensure the contribution adds new value.
Sources: lib/drafting/contribution.ts:25-75, lib/drafting/repository.ts:175-195
API Actions
| Action | API Method | Purpose |
|---|---|---|
| create | POST /api/drafts | Triggers model calls to generate initial draft/brief. |
| update | POST /api/drafts | Saves user edits to the editedText field in the database. |
| approve | POST /api/drafts | Marks the draft as approvedAt after final validation. |
| fetch | GET /api/drafts | Retrieves the latest draft for a specific workspace/opportunity. |
Sources: app/api/drafts/route.ts, lib/drafting/repository.ts
Feedback and Outcomes
The FeedbackPanel records the final result of an opportunity interaction. This data feeds into the learning model to refine future rankings.
Outcome Events
Users record the following status updates:
- Useful / Not useful: General quality feedback.
- Saved / Rejected: Planning and prioritization state.
- Acted on: Confirms the user pursued the opportunity.
- Published URL: Allows the user to record the link to their actual response.
Sources: app/opportunities/[id]/feedback-panel.tsx:5-15, lib/db/schema.ts:327-340
Outcome Data Model
This diagram represents the relationship between opportunities, their drafts, and the resulting feedback events.
Sources: lib/db/schema.ts:340-365
Security and Authorization
Access to opportunity details and drafting capabilities is strictly authorized at the workspace level.
- Workspace Authorization: The page and API routes call
authorizeWorkspace(workspaceId)before performing any database operations. - Data Isolation: All database queries include
where(eq(table.workspaceId, workspaceId))to prevent cross-tenant data leakage. - Input Validation: The
targetDocumentIdis validated as a UUID before usage in repository lookups.
Sources: app/opportunities/[id]/page.tsx:29-45, app/api/drafts/route.ts:25-30, lib/drafting/repository.ts:103-107
The Opportunity Details & Draft Panel provides a controlled pipeline for turning raw social signals into high-quality, evidence-backed community contributions while maintaining strict platform compliance.