README.md

metadata

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

# 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:

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

Or serve it with Python:

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.