Spaces:
Sleeping
Sleeping
| 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. | |