---
title: LeadFlow - Lead Generation
emoji: 🚀
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
---

# 🚀 LeadFlow — Lead Generation & Outreach System

A complete system to scrape business leads from Google Maps, manage them via a premium dashboard, and send WhatsApp outreach messages.

## Features

- 🔍 **Google Maps Scraper** — Search any business type in any city
- 👥 **Lead Management** — Full CRUD with search, filter, and sort
- 💬 **WhatsApp Integration** — One-click messaging via `wa.me` links
- ✉️ **Message Templates** — Create and manage reusable templates
- 📊 **Dashboard Stats** — Real-time lead status overview
- 📄 **CSV Export** — Export all leads for external use
- 📝 **Notes & Follow-ups** — Track conversations and set reminders
- 🎨 **Premium UI** — Dark glassmorphism theme, fully responsive

## Tech Stack

| Layer     | Technology         |
| --------- | ------------------ |
| Backend   | Python + FastAPI   |
| Database  | SQLite             |
| Scraper   | Selenium + Chrome  |
| Frontend  | HTML / CSS / JS    |

## Prerequisites

- **Python 3.9+**
- **Google Chrome** (for the Selenium scraper)

## Setup & Run

### 1. Backend

```bash
# Navigate to backend directory
cd backend

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate    # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
python main.py
```

The API server will start at **http://localhost:8000**  
Swagger docs available at **http://localhost:8000/docs**

### 2. Frontend

Simply open `frontend/index.html` in your browser:

```bash
open frontend/index.html    # macOS
# or
xdg-open frontend/index.html  # Linux
```

Or serve it with Python:

```bash
cd frontend
python3 -m http.server 3000
```

Then open **http://localhost:3000** in your browser.

## Usage

1. **Scrape Leads** — Enter a search query (e.g., "gym in Mumbai") and click "Start Scraping"
2. **Manage Leads** — View leads in the table, search/filter, update statuses
3. **Send WhatsApp** — Click the 💬 button on any lead with a phone number
4. **Edit Templates** — Click "Templates" in the header to create/edit message templates
5. **Export Data** — Click "Export CSV" to download all leads

## API Endpoints

| Method   | Path                | Description             |
| -------- | ------------------- | ----------------------- |
| `POST`   | `/api/scrape`       | Start scraping          |
| `GET`    | `/api/scrape/status`| Scraping job status     |
| `GET`    | `/api/leads`        | List leads (w/ filters) |
| `PUT`    | `/api/leads/{id}`   | Update a lead           |
| `DELETE` | `/api/leads/{id}`   | Delete a lead           |
| `GET`    | `/api/leads/export/csv` | Export to CSV       |
| `GET`    | `/api/stats`        | Dashboard statistics    |
| `GET`    | `/api/templates`    | List templates          |
| `POST`   | `/api/templates`    | Create template         |
| `PUT`    | `/api/templates/{id}` | Update template       |
| `DELETE` | `/api/templates/{id}` | Delete template       |

## ⚠️ Important Notes

- WhatsApp messages are **user-triggered only** (opens in new tab via `wa.me` links)
- No automated messaging or spam — fully compliant with WhatsApp's terms
- Google Maps scraping should be used responsibly with reasonable limits
- The scraper may need periodic updates if Google changes their page structure

## License

MIT — Free for personal and commercial use.