Leadgenius

LeadGenius is a state-of-the-art B2B business intelligence, automated lead harvesting, SEO/technical deficiency auditing, and multi-channel cold outreach platform. Designed with a premium Glassmorphic single-page architecture (supporting Midnight Cyberpunk, Ocean Breeze, Sunset Crimson, and Light Glass themes), it provides sales agencies, marketing firms, and lead auditors with a single, high-fidelity dashboard to extract, score, qualify, and immediately pitch prospects scraped directly from Google Maps.

🗺️ Architectural Workflow

The diagram below maps the B2B pipeline, showing how LeadGenius scrolls Google Maps, indexes target local businesses, parses their websites for architectural failures, scores them, and generates multi-channel outreach pathways.

graph TD
    %% Base Styling Definitions
    classDef main fill:#1e1b4b,stroke:#818cf8,stroke-width:2px,color:#fff;
    classDef worker fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#e2e8f0;
    classDef db fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff;
    classDef api fill:#4c1d95,stroke:#c084fc,stroke-width:2px,color:#fff;

    %% Workflow Nodes
    User["Dashboard Front-End (Tailwind CSS)"]:::main -->|1. Configure & Dispatch Scraping Target| App["app.py Route Handler"]:::main
    App -->|2. Spawn Worker Thread| ScraperSvc["services/scraping_service.py"]:::worker
    
    subgraph Scraping_Auditing_Engine ["Background Scraping & Auditing Engine"]
        ScraperSvc -->|3. Crawl G-Maps Listings| MapsScraper["scraper/maps_scraper.py"]:::worker
        MapsScraper -->|4. Parse Listings & Reviews| ReviewAnalyzer["scraper/review_analyzer.py"]:::worker
        
        ScraperSvc -->|5. Inspect Business Websites| WebAnalyzer["scraper/website_analyzer.py"]:::worker
        WebAnalyzer -->|6. Search Socials & Content Gaps| WebAnalyzer
        WebAnalyzer -->|7. Extract Emails via Spider| EmailExtractor["scraper/email_extractor.py"]:::worker
    end

    MapsScraper & WebAnalyzer & EmailExtractor -->|8. Store Scraped Datasets| DBModels["database/models.py (SQLAlchemy Schema)"]:::db
    DBModels -->|9. Compute Audit Score / Badges| ScoringSvc["services/scoring_service.py"]:::worker
    ScoringSvc -->|10. Persist Scores & Badges| SQLite[("leads_extractor.db")]:::db

    User -->|11. Select Saved SMTP Profiles| OutreachPanel["Multi-Channel Outreach Suite"]:::main
    OutreachPanel -->|12. Request Personalization Drafts| QualificationSvc["services/qualification_service.py"]:::worker
    OutreachPanel -->|13. Send Direct Bulk/Single Outreach| CampaignSvc["services/campaign_service.py"]:::worker
    
    CampaignSvc -->|Direct Dispatch| EmailGateway["SMTP Server (Gmail App Passwords)"]:::api
    CampaignSvc -->|Open pre-filled wa.me APIs| WhatsAppGateway["WhatsApp API Gateway"]:::api

    %% Node classes
    class User,OutreachPanel main;
    class App,ScraperSvc,MapsScraper,ReviewAnalyzer,WebAnalyzer,EmailExtractor,ScoringSvc,QualificationSvc,CampaignSvc worker;
    class DBModels,SQLite db;
    class EmailGateway,WhatsAppGateway api;

✨ Features Spotlight

🚀 1. Headless B2B Lead Harvester

• Dynamic Geolocation Pinning: Features an interactive Leaflet.js Map Picker. Drop a pin anywhere in the world to automatically resolve local postal descriptors via OpenStreetMap's Nominatim reverse geocoding API.
• Auto-Resuming & Target Deduplication: Identifies if a scraping query and location combination is already loaded. Instead of throwing duplicates, it automatically resumes, extends existing targets, and pulls fresh database records in real-time.
• Automated Driver Lifecycle: Dynamically checks host computer Chrome installations and automatically downloads/safeguards matching Chromedriver binaries.

🛡️ 2. Deep-Scan Website Deficiency Auditor

Analyzes business websites on key metrics to calculate B2B opportunity scores:

• Security Audits: Scans for missing SSL configurations (HTTP fallback).
• Communication Gaps: Checks for absence of generic contact forms or visible contact emails/phones.
• Layout Integrity: Analyzes code patterns for outdated website themes or slow loading times (>2.0s).
• Social Footprints & Trackers: Discovers links for Facebook, Instagram, LinkedIn, and checks for integration trackers like Google Analytics or Meta Pixel.

📊 3. Visual Opportunity Analytics & Geographic Hotspots

• Deficiency Radar Diagrams: Uses Chart.js to render radial deficiency distributions showing overall structural failure aggregates.
• Badged Lead Qualification: Segregates prospects into opportunity brackets (HOT / WARM / COLD) based on customizable scoring weights.
• Interactive Hotspots Viewer: Plots leads geographically on a high-fidelity dark-themed basemap. Points are dynamically color-coded to identify outreach priorities. Includes a built-in frame to inspect Google Maps pages inside the dashboard.

📧 4. Multi-Channel Outreach Engine

• Multi-Channel Dispatch: Supports direct email dispatch (SMTP) and instant WhatsApp messaging (via pre-filled wa.me browser redirect links) or both at the same time.
• Local SMTP Profile Manager: Allows users to save, switch, and delete multiple SMTP configuration profiles using localStorage. Instantly swap between different outreach mailboxes without losing credentials.
• Mock Testing Suite: Perform live-sandbox dry runs to test email designs and subject headings before launching live B2B campaigns.
• Export Utilities: Filter leads dynamically on the dashboard and export structured datasets to CSV, Excel, or JSON.

📁 Repository Structure Map

Below is a structured map of the LeadGenius codebase. You can navigate directly to the individual codebase files by clicking their links:

| Path / File | Type | Description | | :--- | :---: | :--- | | 📄 app.py | Python | Central Flask application containing SaaS routes, B2B extraction queries, qualification layers, and outreach controls. | | 📄 config.py | Python | Configuration controller mapping database URLs, Chrome configurations, and lead scoring engine weights. | | 📄 .gitignore | Git Config | Comprehensive ignore rules covering local environments, caches, driver binaries, SQLite files, and secret folders. | | 📄 requirements.txt | Text | Pip package dependency manifest mapping exact runtime versions. | | 📄 verify_imports.py | Python | Module syntax and dependencies integration check. | | 📂 database/ | Directory | Database schemas and initialization. | |     â”œâ”€ 📄 db.py | Python | Initializes SQLAlchemy database connection instance. | |     â””─ 📄 models.py | Python | Defines relational models (ScrapingJob, Lead, WebsiteAnalysis, LeadScore). | | 📂 scraper/ | Directory | Dynamic browser scraper and analyzers. | |     â”œâ”€ 📄 maps_scraper.py | Python | Selenium controller scrolling Google Maps listings to gather target locations. | |     â”œâ”€ 📄 website_analyzer.py | Python | Analyzes target websites for SSL, loading speeds, and structural deficiencies. | |     â”œâ”€ 📄 email_extractor.py | Python | Crawls site subpages to discover B2B contact emails. | |     â”œâ”€ 📄 review_analyzer.py | Python | Gathers and analyzes Google reviews. | |     â”œâ”€ 📄 filters.py | Python | Parses database query strings to apply granular dashboard filters. | |     â””─ 📄 utils.py | Python | Automatically downloads and handles Google Chromedriver dependencies. | | 📂 services/ | Directory | Business logic and integrations layer. | |     â”œâ”€ 📄 scraping_service.py | Python | Manages background threads for scraping runs. | |     â”œâ”€ 📄 scoring_service.py | Python | Calculates opportunity points and applies hot/warm/cold badges. | |     â”œâ”€ 📄 qualification_service.py | Python | Formulates deficiencies checklists and writes customized AI prompt hooks. | |     â”œâ”€ 📄 campaign_service.py | Python | Compiles custom outreach pitches and runs the SMTP dispatch engine. | |     â””─ 📄 export_service.py | Python | Formats and compiles databases into CSV, JSON, and Excel formats. | | 📂 static/ | Directory | Core frontend CSS and JS assets. | |     â”œâ”€ 📂 css/ | Directory | Custom styles for active theming overlays. | |     â””─ 📂 js/ | Directory | Front-end scripts. | |         â””─ 📄 app.js | JS | Frontend state manager. Configures Leaflet Maps, Chart.js displays, and SMTP profile states. | | 📂 templates/ | Directory | HTML dashboard page layouts. | |     â””─ 📄 dashboard.html | HTML | Core dashboard markup. Includes glassmorphic controls, map canvases, and outreach modules. |

⚙️ Core Configuration Settings

The system loads settings from .env using config.py. You can adjust lead scoring priorities by updating the SCORING_WEIGHTS dictionary in config.py:

SCORING_WEIGHTS = {
    'no_website': 25,        # 25 Pts added if no website is found
    'outdated_website': 15,  # 15 Pts added if layout/themes are outdated
    'no_ssl': 10,            # 10 Pts added if website lacks an SSL certificate
    'low_reviews': 15,       # 15 Pts added if business has < 10 reviews
    'low_rating': 10,        # 10 Pts added if Google Rating is < 4.0 stars
    'no_phone': 5,           # 5 Pts added if no phone is listed on Google
    'no_email': 10,          # 10 Pts added if no email is discovered on website
    'missing_socials': 5,    # 5 Pts added if no social accounts are linked
    'missing_cta': 10,       # 10 Pts added if there is no strong Call To Action on the homepage
    'no_analytics': 5        # 5 Pts added if meta/google tracking script is missing
}

Opportunity scores range from 0 to 100. The higher the score, the more severe the business's deficiencies, qualifying them as a prime prospect:

• 🔥 HOT Angle: Score $\ge$ 60 (Red marker badge)
• ⚡ WARM Angle: Score 35–59 (Amber marker badge)
• ❄️ COLD Angle: Score $<$ 35 (Emerald marker badge)

🚀 Setup & Installation Guide

Follow these steps to set up LeadGenius on your local workstation:

1. Prerequisites

Ensure you have the following installed on your machine:

• Python 3.8 or higher
• Google Chrome (Selenium will interface with it)
• Active internet connection (to fetch map tiles and check website URLs)

2. Clone the Repository

git clone https://github.com/RasikhAli/LeadGenius.git
cd LeadGenius

3. Initialize the Virtual Environment

Create a clean virtual environment and install the required dependencies:

On Windows:

python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt

On macOS / Linux:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. Configure Environment Variables

Create a file named .env in the root folder of the project. Copy and paste the configuration keys below, adjusting them to your preferences:

# --- Core Flask Settings ---
SECRET_KEY=leadgenius-super-secure-production-key
FLASK_DEBUG=True

# --- Local Databases ---
DATABASE_URL=sqlite:///leads_extractor.db

# --- Headless Crawlers ---
CHROME_HEADLESS=True
SCRAPING_TIMEOUT=15
MAX_THREADS=4

5. Verify the Installation

Run the verification script to confirm that all directories, dependencies, database models, and scraper engines are initialized:

python verify_imports.py

[!NOTE] If all checks print [OK], you are ready to start the application.

6. Launch the Platform

Start the local server:

python app.py

After starting the server, open your web browser and navigate to:

http://127.0.0.1:5000

📧 Configuring Multi-Channel Outreach

To send B2B email campaigns from the LeadGenius dashboard, you need to configure a valid SMTP provider. For Gmail, follow the instructions below:

Setting Up Gmail App Passwords

1. Sign in to your Google Account.
2. Navigate to Security settings.
3. Under How you sign in to Google, make sure 2-Step Verification is enabled.
4. Click on 2-Step Verification, scroll to the bottom, and select App passwords.
5. Select Mail as the app and Other (Custom name) as the device (name it LeadGenius).
6. Click Generate. Copy the 16-character passcode shown in the window.
7. Open the Outreach Suite on the LeadGenius dashboard. In the SMTP Settings panel, enter:
   • SMTP Host: smtp.gmail.com
   • SMTP Port: 465
   • Sender Email: Your Gmail address
   • App Password: The generated 16-character password (without spaces)
8. Click Save SMTP Profile to save it locally. You can now use the credentials for bulk/single email campaigns.

[!TIP] WhatsApp Outreach: No SMTP settings are required for WhatsApp. The outreach engine automatically parses phone numbers, sanitizes them to comply with international dialing formats, and constructs https://wa.me/ URLs populated with custom AI deficiency pitches that open in your browser.

📜 Licensing

This project is open-source and available under the MIT License. Feel free to use, modify, and distribute it for personal or commercial projects.