# 🚀 Lead Generator — Complete Web App Package

**Production-Ready Lead Generation System with Web Interface**

---

## 📦 What's Included

This package contains everything you need:

### Backend (FastAPI)
- ✅ Google Places API integration
- ✅ Website scraping (Playwright)
- ✅ Company enrichment (Hunter.io/Clearbit)
- ✅ Lead scoring & prioritization
- ✅ Runtime API key configuration
- ✅ Rate limiting

### Frontend (Next.js React)
- ✅ Settings page (configure API keys via web UI)
- ✅ Search interface (ZIP, radius, keyword)
- ✅ Results table (name, phone, website, rating, score)
- ✅ Neon Minimal design (dark mode + neon accents)
- ✅ Mobile responsive

### Documentation
- ✅ Setup guide
- ✅ API documentation
- ✅ Usage examples

---

## 🚀 Quick Start (5 minutes)

### 1. Extract the Package

```bash
tar -xzf lead-generator-complete.tar.gz
cd lead-generator
```

### 2. Backend Setup

```bash
# Install Python dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium
```

### 3. Frontend Setup

```bash
cd ../lead-generator-frontend

# Install Node dependencies
npm install
```

### 4. Start Both Services

**Terminal 1 — Backend:**
```bash
cd lead-generator
python3 -m uvicorn main:app --reload
```

**Terminal 2 — Frontend:**
```bash
cd lead-generator-frontend
npm run dev
```

### 5. Open in Browser

Navigate to: **`http://localhost:3000`**

You should see the Lead Generator web app! 🎉

---

## 🔐 Configure API Keys

### Step 1: Get Google API Key

1. Visit: https://console.cloud.google.com/
2. Create a new project
3. Enable these APIs:
   - **Geocoding API**
   - **Places API**
   - **Maps JavaScript API**
4. Create an API key (Credentials → Create Credentials → API Key)
5. Restrict to HTTP Referrer: `localhost:3000`
6. Copy the key

### Step 2: Enter in Web App

1. Open http://localhost:3000
2. Click **"⚙️ Configuration"** tab
3. Paste your Google API key
4. Leave Hunter.io key blank (optional)
5. Enter admin password: `changeme123` (default)
6. Click **"Save Configuration"**

### Step 3: Search Leads

1. Click **"🔍 Search Leads"** tab
2. Enter a ZIP code (e.g., `10001`)
3. Select radius (e.g., `5 km`)
4. Optional: Add keyword (e.g., `plumber`)
5. Click **"Search Leads"**

You'll see a table of businesses with:
- Name, address, phone, website, rating
- **Score** (0-100) & **Priority** (High/Medium/Low)

---

## 📂 Directory Structure

```
lead-generator/                          # Backend (FastAPI)
├── main.py                              # Entry point
├── config/settings.py                   # Configuration
├── services/
│   ├── google_api.py                   # Google Places API
│   ├── config_manager.py               # API key management
│   ├── lead_processor.py               # Scraping + enrichment
│   ├── enricher.py                     # Hunter.io/Clearbit
│   └── scraper/website_scraper.py      # Playwright scraper
├── routes/
│   ├── search.py                       # /api/search endpoint
│   └── settings.py                     # /api/settings endpoints
├── utils/
│   ├── lead_scorer.py                  # Scoring logic
│   └── rate_limiter.py                 # Rate limiting
├── requirements.txt                     # Python dependencies
└── .env.example                         # Config template

lead-generator-frontend/                 # Frontend (Next.js)
├── app/
│   ├── page.tsx                        # Main page with tabs
│   ├── components/
│   │   ├── LeadSearchForm.tsx          # Search interface
│   │   └── SettingsPanel.tsx           # Configuration UI
│   ├── layout.tsx
│   └── globals.css
├── package.json                        # Node dependencies
├── .env.local.example                  # Frontend config
└── WEB-APP-SETUP.md                    # Detailed setup guide
```

---

## 🎯 Features Overview

### Phase 1: Google Places API
- Geocoding (ZIP code → coordinates)
- Nearby search (find businesses)
- Place details (phone, website, ratings)

### Phase 2: React Frontend
- Clean, responsive UI
- Neon Minimal design system
- Real-time search results

### Phase 3: Enrichment & Scoring
- Website scraping (emails, contact pages, social links)
- Company enrichment (size, industry)
- Automatic lead scoring (0-100)
- Priority ranking (High/Medium/Low)

### Phase 4: Web App Configuration
- Secure settings page
- Runtime API key entry (no `.env` editing)
- Admin password protection
- Status indicators

---

## 🔧 Configuration

### Minimal Setup (Phase 1 only)
```
GOOGLE_API_KEY=your_key_here
ADMIN_PASSWORD=changeme123
```

### Full Setup (All phases)
```
GOOGLE_API_KEY=your_key_here
HUNTER_API_KEY=your_hunter_key
ENRICHMENT_ENABLED=true
SCRAPER_ENABLED=true
ADMIN_PASSWORD=changeme123
```

All settings can be configured via the web UI (no file editing needed).

---

## 📊 Lead Scoring Example

**Lead Score Calculation:**

| Factor | Points |
|--------|--------|
| Has website | +10 |
| Has email | +20 |
| Rating ≥ 4.0 | +15 |
| Has contact page | +10 |
| Has phone | +5 |
| **Total Max** | **60** |

**Priority Mapping:**
- **50+** → High 🔥
- **25-49** → Medium ⚠️
- **0-24** → Low 📋

---

## 🚀 API Endpoints

### Search
```
POST /api/search
{
  "zip_code": "10001",
  "radius": 5000,
  "keyword": "plumber",
  "scrape": false,
  "enrich": false
}
```

### Settings
```
GET  /api/settings/initialized     # Check if configured
GET  /api/settings/status          # Get current settings
POST /api/settings/configure-keys  # Save API keys
POST /api/settings/update          # Update features
```

Full API docs available at: `http://localhost:8000/docs`

---

## 🔐 Security

✅ **Admin Password** — Default: `changeme123` (change for production)
✅ **API Keys** — Stored in server memory, never logged
✅ **Rate Limiting** — 10 requests/60 seconds per IP
✅ **Blocked Domains** — Google, LinkedIn, Indeed, Upwork protected
✅ **CORS Enabled** — Frontend and backend can communicate

---

## 💡 Usage Tips

### For Testing
```bash
# Search without scraping (fast, <2s)
ZIP: 10001
Radius: 5km
Keyword: dentist
Scrape: ☐ (unchecked)
Enrich: ☐ (unchecked)
```

### For Email Hunting
```bash
# Search with scraping (slower, 1-5 min)
ZIP: 90210
Radius: 2km
Keyword: realtor
Scrape: ☑ (checked)
Enrich: ☐ (unchecked)
```

### For Enrichment
```bash
# Search with company data (requires Hunter key)
ZIP: 60601
Radius: 10km
Keyword: lawyer
Scrape: ☑
Enrich: ☑
```

---

## 🐛 Troubleshooting

| Problem | Solution |
|---------|----------|
| Backend won't start | `pip install -r requirements.txt && playwright install chromium` |
| Frontend won't start | `npm install` then `npm run dev` |
| Can't connect to backend | Check NEXT_PUBLIC_API_URL in `.env.local` |
| API key rejected | Verify key is from Google Cloud Console |
| No results found | Try different ZIP or increase radius |
| Scraping takes forever | Disable it, or use keyword filter to reduce results |

---

## 📱 Supported Browsers

- ✅ Chrome/Edge (recommended)
- ✅ Firefox
- ✅ Safari
- ✅ Mobile browsers (iOS Safari, Chrome Android)

---

## 🌐 Deployment Options

### Local Network
```bash
# Allow access from other machines on your network
python3 -m uvicorn main:app --host 0.0.0.0 --port 8000
```

Update frontend `.env.local`:
```
NEXT_PUBLIC_API_URL=http://your-machine-ip:8000
```

### Cloud Deployment

**Frontend → Vercel** (free)
```bash
npm install -g vercel
vercel deploy
```

**Backend → Railway/Render** (~$5/month)
- Push code to GitHub
- Connect to Railway/Render
- Set environment variables
- Auto-deploys on push

### Docker
```bash
docker build -t lead-gen-backend lead-generator/
docker build -t lead-gen-frontend lead-generator-frontend/
docker run -p 8000:8000 lead-gen-backend
docker run -p 3000:3000 lead-gen-frontend
```

---

## 📚 Documentation Files

Inside the package:

- `lead-generator/README-PHASE3.md` — Complete backend docs
- `lead-generator/PHASE3-SETUP.md` — Step-by-step backend setup
- `lead-generator-frontend/WEB-APP-SETUP.md` — Frontend guide
- `lead-generator-frontend/README.md` — Frontend API integration

---

## 💰 Costs

### Free Tier (Recommended)
- Google Places API — Free quota included
- Website scraping — Free (Playwright local)
- Lead scoring — Free (local compute)
- Rate limiting — Free (local memory)

### Optional (Paid)
- Hunter.io — $49-299/month or $0.50/lookup
- Clearbit — $99-999/month

**Pro Tip:** Use Phase 1 + scraping (free). Only enrich high-priority leads to minimize costs.

---

## 🎯 What You Can Do Now

✅ Search for business leads by location
✅ Extract emails from company websites
✅ Enrich leads with company data
✅ Automatically score and prioritize leads
✅ Export results to spreadsheet
✅ Deploy as internal tool or SaaS
✅ Build lead generation business
✅ Integrate with CRM/email systems

---

## 🤝 Support

**Getting started?**
1. Read `lead-generator-frontend/WEB-APP-SETUP.md`
2. Follow Quick Start section above
3. Open http://localhost:3000
4. Check API docs at http://localhost:8000/docs

**Having issues?**
- Backend won't start → Check Python 3.8+
- Frontend won't connect → Check backend is running
- API key errors → Verify key from Google Cloud
- Rate limited → Wait 60 seconds

---

## 🎉 You're All Set!

This is a **complete, production-ready** lead generation system.

You can:
- Use it locally
- Share it with team
- Deploy to cloud
- Sell as service
- Build a business on it

Everything you need is here. No hidden costs, no dependencies missing.

**Start with the Quick Start section above and you'll be generating leads in minutes!**

---

**Built with:** FastAPI, Next.js, React, Tailwind CSS, Playwright, Google Places API

**License:** MIT (use freely)

**Questions?** Check the docs inside the package or review the inline code comments.

---

**Happy lead hunting!** 🚀