LeadFlow AI is a premium B2B LinkedIn lead generation platform that combines AI-powered intelligence with human oversight to help sales professionals and consultants identify, qualify, and engage high-value prospects at scale.

• Manual LinkedIn prospecting takes 10-20 minutes per prospect
• Generic messages get ignored (low response rates)
• No systematic way to prioritize valuable leads
• Difficult to scale outreach without losing personalization

• ⚡ 40x Time Savings: AI handles research, scoring, and drafting in <30 seconds
• 🎯 Smart Targeting: Multi-factor scoring (company size, influence, activity, events)
• ✍️ Personalized at Scale: AI-crafted messages based on recent posts and activity
• 🔒 LinkedIn-Safe: Rate-limited automation that respects platform rules
• 📊 Data-Driven: Real-time analytics to optimize your outreach

• Evaboot Integration (Primary) - Extract validated leads from Sales Navigator
• CSV upload with validation and deduplication
• PhantomBuster enrichment for additional data

• Automatic scraping of followers, connections, and mutual connections
• Last 10 LinkedIn posts analyzed for engagement signals
• Company data extraction and validation
• Event/conference keyword detection

Intelligent lead ranking based on:

• Company size and industry relevance
• Follower influence and network strength
• Recent activity and engagement
• Event participation and speaking
• Mutual connections
• Title/role relevance

Output: Tier A/B/C classification for instant prioritization

• Powered by OpenAI GPT-4o
• References specific post content (not generic)
• Includes event mentions when detected
• Tone customization (professional/casual/direct)
• <300 characters (LinkedIn optimized)

• Beautiful dashboard for reviewing generated messages
• Inline editing with real-time save
• Bulk approve for Tier A leads
• View profile, posts, and score breakdown

• n8n workflow orchestration
• PhantomBuster Network Booster integration
• Rate limiting (1-3 connections/hour)
• Random delays for human-like behavior
• Activity logging and tracking

• Connection acceptance rate tracking
• Response rate monitoring
• Score distribution analysis
• Campaign performance metrics
• ROI calculation

Design Philosophy: Premium dark-first aesthetic with glassmorphism and intelligent micro-interactions

• Primary Color: Electric Blue #2563EB → Cyan #06B6D4 gradient
• Typography: Inter (body) + Outfit (display headlines)
• Style: Dark backgrounds (#0A0E1A), glassmorphic cards, gradient accents
• Voice: Intelligent, empowering, professional, modern, human

1. Clarity Over Cleverness - Intuitive, user-friendly design
2. Data-Driven Aesthetics - Beautiful visualizations that tell stories
3. Intelligent Minimalism - Every element serves a purpose
4. Premium Dark-First - Optimized for professionals working long hours
5. Micro-interactions Matter - Subtle animations provide delight

Full brand guide: docs/BRAND_IDENTITY.md

React 18 + TypeScript          - Modern, type-safe UI
Vite                           - Lightning-fast dev server
Tailwind CSS                   - Utility-first styling with custom design system
React Router v6                - Client-side routing
Lucide Icons                   - Consistent 2px stroke icons

Convex                         - Real-time serverless database + functions
Clerk                          - Authentication and user management
Convex Storage                 - File uploads (CSV)
Convex Scheduled Functions     - Cron jobs for automation

OpenAI GPT-4o                  - Message personalization
Convex Vector Search           - Semantic post analysis
n8n                            - Workflow orchestration
PhantomBuster                  - LinkedIn-safe scraping & automation
Evaboot                        - Lead extraction from Sales Navigator ⭐

Vercel                         - Frontend hosting (auto-deploy)
Convex Cloud                   - Backend (auto-scaling)
Sentry                         - Error tracking
PostHog                        - Product analytics

We've created comprehensive documentation covering every aspect of the project:

Total Documentation: 114.5 KB | 4,530+ lines

• Node.js 18+ installed
• Git installed
• Accounts for: Clerk, Convex, OpenAI, Evaboot

# 1. Clone repository
git clone <your-repo-url>
cd LeadGenSaaS

# 2. Install dependencies
npm install

# 3. Set up environment variables
Copy-Item .env.example .env.local
# Fill in your API keys (see docs/QUICK_START.md)

# 4. Initialize Convex backend
npx convex dev

# 5. Start development server (new terminal)
npm run dev

Visit http://localhost:5173 🎉

Detailed setup: docs/QUICK_START.md

Open demo/landing-page.html in your browser to see:

• ✅ Premium dark-first design
• ✅ Glassmorphic cards with backdrop blur
• ✅ Gradient buttons with hover glow
• ✅ Smooth animations on scroll
• ✅ Responsive mobile-first layout
• ✅ Complete brand implementation

(Coming soon after implementation begins)

companies    - Company profiles (name, industry, size, location)
people       - Lead profiles (contact info, enrichment, scores)
posts        - LinkedIn posts (content, engagement, AI analysis)
campaigns    - Outreach campaigns (targeting, templates, limits)
activities   - Activity log (connections sent, accepted, replied)
users        - User accounts (via Clerk integration)

Full schema: docs/PIV_FRAMEWORK_PLAN.md Section 1.4

This project follows Cole Medin's PIV Framework for agentic AI coding:

• Clear requirements documented (4,530+ lines)
• Database schema defined (6 tables)
• Features broken into atomic tasks
• Architecture decided and documented
• Brand identity established
• Content strategy planned
• Design system created

• Build one feature at a time
• Reference PIV plan for context
• Use design system for all UI
• Apply brand tokens consistently
• Test after each feature

• Functionality tests
• Performance checks (page load <2s)
• UX validation
• Accessibility audit (WCAG AA)
• Bug fixes and refinement

Learn more: Cole Medin on YouTube

• Requirements gathering
• Technical architecture
• Database schema
• Feature breakdown
• Brand identity system
• Content strategy
• Design system
• Implementation roadmap

• React + Vite + TypeScript setup
• Design tokens implementation (CSS variables)
• Convex backend initialized
• Clerk authentication
• Base component library

• Evaboot CSV upload feature
• PhantomBuster integration
• Profile enrichment pipeline
• Database CRUD operations

• Multi-factor scoring engine
• AI message generation (OpenAI GPT-4o)
• Event keyword detection
• Quality testing

• Approval dashboard
• Analytics charts
• n8n automation workflows
• Final testing & polish

Detailed timeline: docs/ROADMAP.md

• Time Savings: 40x faster (30s vs 10-20 min per prospect)
• Message Quality: >80% approval rate (minimal edits needed)
• Connection Acceptance: >50% (industry average: 35%)
• Lead Enrichment: >95% success rate

• User sign-ups: 100 in Month 1
• Active users: >60% weekly activity
• NPS score: >50
• Churn: <10% monthly

• Blog traffic: +200% YoY
• Email subscribers: 5,000 in Q1
• LinkedIn engagement: >8% rate
• Trial conversions: 5% from content

# Development
npx convex dev          # Terminal 1: Convex backend
npm run dev             # Terminal 2: React frontend

# Build for production
npm run build
npx convex deploy --prod

# Deploy frontend
vercel deploy --prod

# Code quality
npm run lint
npm run format
npm run type-check

• ✅ Only public LinkedIn data stored
• ✅ API keys encrypted in environment variables
• ✅ Clerk handles authentication securely
• ✅ Rate limiting prevents LinkedIn bans
• ✅ GDPR-compliant delete endpoint
• ✅ Privacy policy included
• ✅ Accessibility (WCAG AA compliance)

LeadGenSaaS/
├── .agents/
│   └── workflows/              # Implementation guides
├── convex/                     # Backend (Convex)
│   ├── schema.ts              # Database schema
│   ├── people.ts              # Lead CRUD
│   ├── scoring.ts             # Scoring algorithm
│   └── messageGeneration.ts   # AI message gen
├── src/                       # Frontend (React)
│   ├── components/            # UI components
│   │   ├── ui/               # Base components (design system)
│   │   ├── dashboard/        # Dashboard features
│   │   └── leads/            # Lead management
│   ├── pages/                # Route pages
│   ├── hooks/                # Custom React hooks
│   ├── lib/                  # Utilities
│   └── styles/               # Global styles & design tokens
├── demo/                      # Demo files
│   └── landing-page.html     # Live landing page demo
├── docs/                      # Documentation (4,530+ lines)
│   ├── PROJECT_OVERVIEW.md   # Quick reference (START HERE)
│   ├── BRAND_IDENTITY.md     # Brand bible
│   ├── CONTENT_STRATEGY.md   # Marketing plan
│   ├── DESIGN_SYSTEM.md      # UI library
│   ├── PIV_FRAMEWORK_PLAN.md # Technical blueprint
│   ├── QUICK_START.md        # Setup guide
│   ├── ROADMAP.md            # Timeline
│   └── SCOPE_OF_WORK.md      # Requirements
└── .env.example               # Environment template

• Read docs/PROJECT_OVERVIEW.md
• Review brand identity in docs/BRAND_IDENTITY.md
• Get API keys (Clerk, Convex, OpenAI, Evaboot)

• Complete environment setup
• Initialize Convex schema
• Set up Clerk authentication
• Create base components with design system
• Test Evaboot export/import workflow

• Complete Week 1: Foundation
• Complete Week 2: Data Layer
• Complete Week 3: Intelligence
• Complete Week 4: UI & Automation
• Internal beta testing

Start here: docs/QUICK_START.md

• Cole Medin (PIV Framework): https://www.youtube.com/@ColeMedin
• Convex Documentation: https://docs.convex.dev
• Clerk Authentication: https://clerk.com/docs
• Evaboot (Lead Extraction): https://www.evaboot.com
• PhantomBuster API: https://docs.phantombuster.com
• OpenAI API: https://platform.openai.com/docs
• Tailwind CSS: https://tailwindcss.com
• Lucide Icons: https://lucide.dev

• Framework: Cole Medin's PIV Framework
• Client: RE ALINE (Andrew Line) → Vistage (Mary Forte)
• Budget: $1,000 (at-cost engineering)
• Timeline: 4 weeks to MVP
• Brand Name: LeadFlow AI
• Tagline: Intelligence Meets Opportunity

Planning Phase:      ████████████████████ 100% ✅
Brand & Design:      ████████████████████ 100% ✅
Week 1 (Foundation): ░░░░░░░░░░░░░░░░░░░░   0%
Week 2 (Data Layer): ░░░░░░░░░░░░░░░░░░░░   0%
Week 3 (Intelligence):░░░░░░░░░░░░░░░░░░░░   0%
Week 4 (UI/Auto):    ░░░░░░░░░░░░░░░░░░░░   0%

Overall: 30% (Planning + Brand/Design Complete, Implementation Starting)

Private project - All rights reserved