SanatiLeads/docs/phase-3-opportunities-and-workflow.md

Phase 3 — Opportunities Persistence & Workflow

Goals

• Persist opportunity search results in Convex.
• Enable lead management (status, notes, tags).
• Add filtering, pagination, and basic bulk actions.

Scope

• Write opportunities to Convex during search.
• Read opportunities from Convex in the UI.
• Implement lead status changes and notes/tags.

Detailed Tasks

1. Persist opportunities

   • Update /api/opportunities to call opportunities.upsertBatch after scoring.
   • Dedupe by URL + projectId.
   • Store analysisId + projectId on each opportunity.

2. Load opportunities from Convex

   • Replace local state-only data with Convex query.
   • Add pagination and “Load more” to avoid giant tables.

3. Filtering & sorting

   • Filters: status, intent, platform, min relevance score.
   • Sorting: relevance score, createdAt.

4. Lead workflow actions

   • Status change: new → viewed/contacted/responded/converted/ignored.
   • Add notes + tags; persist via mutation.
   • Optional: quick bulk action for selected rows.

5. UI feedback

   • Show counts by status.
   • Empty states for no results or no saved opportunities.

Dependencies

• Requires Phase 1 schema and Phase 2 project + analysis persistence.

Acceptance Criteria

• Opportunities persist across refresh and sessions.
• Status/notes/tags are stored and reflected in UI.
• Filters and pagination are usable.

Risks

• Serper or direct Google scraping limits; need clear UX for failed searches.

Notes

• Keep raw search results transient; only store scored opportunities.