Cold ScoutCold Scout
HomeFree AuditDirectoryPricingDocsSponsorGet Started
Documentation

Platform
Resources

Everything you need to set up, configure, and deploy your AI-powered lead generation system.

42Environment Variables
9Integrations
5Pipeline Stages
24/7Automation

On This Page

System ArchitectureAutomation PipelineTechnology StackLocal Setup GuideAPI Keys & ServicesEnvironment VariablesProduction DeploymentProduction Architecture

Architecture

System Architecture

The platform orchestrates an asynchronous pipeline with robust state management across three deployment layers.

Admin DashboardReact + Vite + TailwindREST APIFastAPI ServerPython 3.11+PostgreSQLSupabase ManagedAPSchedulerCron TriggerGoogle PlacesDiscoveryPlaywrightWeb ScrapingGroq / Llama 3AI QualificationGroq AIEmail GenerationBrevo SMTPOutreachTelegram Alerts

Pipeline

Automation Pipeline

Five automated stages execute daily, managed by APScheduler with configurable IST scheduling.

01

Discovery

Google Places API scrapes local businesses matching your target industry and location parameters.

02

Qualification

Groq Llama 3 analyzes scraped website data against your Ideal Customer Profile (ICP).

03

Personalization

AI generates hyper-personalized email copy analyzing prospect pain points and value propositions.

04

Outreach

Brevo SMTP delivers emails with configurable intervals, rate limiting, and domain verification.

05

Reporting

Daily Telegram alerts on system health, lead counts, qualification rates, and campaign metrics.

Stack

Built With

Python 3.11+

Core backend runtime

FastAPI

Async REST API framework

React 18

Frontend UI library

Vite 5

Next-gen build tool

TailwindCSS

Utility-first styling

PostgreSQL

Relational database

Docker

Container deployment

TypeScript

Type-safe frontend

Setup

Local Development Setup

Follow these steps meticulously to run the complete system locally.

Backend Setup (FastAPI)

bash
# Option A: Download the free self-hosted package from GitHub Releases
# https://github.com/colddsam/coldscout/releases?q=oss-v

# Option B: Clone the full repository
git clone https://github.com/colddsam/coldscout.git
cd coldscout/coldscout-oss
bash
python -m venv venv

# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate
bash
pip install -r requirements.txt
playwright install chromium

Ensure your .env file is configured first.

bash
python scripts/create_tables.py
python scripts/seed_admin.py

💡 Save the generated admin credentials to log into the dashboard.

bash
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

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

Frontend Setup (React Dashboard)

bash
cd frontend/localleadpro-dashboard
bash
npm install

Requires Node.js 18+

Create a .env file:

env
# Backend API Location
API_BASE_URL=http://localhost:8000

# API Key (injected by proxy)
API_KEY=your_secret_api_key_here

# Frontend Proxy Access
VITE_API_BASE_URL=http://localhost:3000
VITE_API_KEY=your_secret_api_key_here
bash
# Starts proxy on :3000 and Vite on :5173
npm run dev

Dashboard available at: http://localhost:5173

bash
npm run build

The dist/ output can be deployed to Vercel, Netlify, or AWS S3.

Integrations

API Keys & Services

All integrations are available on free tiers. Follow each guide to collect your keys.

Groq AI

Llama 3 for lead qualification & email generation

GROQ_API_KEY
1

Sign up at Groq Cloud

2

Navigate to API Keys

3

Create API Key

4

Copy key (starts with gsk_)

Google Places

Local business discovery engine

GOOGLE_PLACES_API_KEY
1

Create GCP Project

2

Enable Places API

3

Create Credentials → API Key

4

$200/mo free credit included

Supabase

Managed PostgreSQL database

DATABASE_URL
1

Create free tier project

2

Settings → Database → Copy URI

3

Add +asyncpg to URI

4

Copy URL & Anon Key from API settings

Brevo SMTP

Transactional email outreach

BREVO_SMTP_PASSWORD
1

Sign up free

2

Profile → SMTP & API tab

3

Generate new SMTP key

4

Verify sender domain/email

Gmail IMAP

Inbound reply tracking

IMAP_PASSWORD
1

Enable 2-Step Verification

2

Search "App Passwords"

3

Create app: "ColdScout"

4

Copy 16-char code

Telegram Bot

Real-time system alerts

TELEGRAM_BOT_TOKEN
1

Message @BotFather → /newbot

2

Set name & username

3

Copy API Token

4

Get Chat ID from @userinfobot

Cron-Job.org

Keep-alive pings & scheduling

CRON_JOB_API_KEY
1

Create free account

2

Settings → API Keys

3

Generate new key

4

Run setup_cronjob.py script

GitHub Actions

CI/CD pipeline automation

RENDER_DEPLOY_HOOK
1

Repo → Settings → Secrets

2

Add all env vars as secrets

3

Get Render Deploy Hook URL

4

Push to main triggers deploy

Core Secrets

Session encryption & API security

APP_SECRET_KEY
1

Run generate_secrets.py

2

Auto-generates secure hex strings

3

Appends to .env file

4

Generates APP_SECRET_KEY, API_KEY, SALT

Configuration

Environment Variables

42 tokens required for full functionality. All must be mirrored across Render and Vercel.

VariableDescription
APP_ENVproduction or development
APP_SECRET_KEYHex string for session salt
API_KEYPublic access key for API
SECURITY_SALTRandom string for hashing
BACKEND_CORS_ORIGINSComma-separated allowed domains
APP_URLYour Render Service URL
IMAGE_BASE_URLCDN link for branding assets
VITE_API_KEY(Frontend) Must match Backend API_KEY

Deployment

Production Deployment

Three services, three steps. Your system running 24/7 in the cloud.

Step 1

Database — Supabase

  1. 1Create a project on Supabase.com (Free Tier)
  2. 2Go to Project Settings → Database
  3. 3Copy the URI connection string
  4. 4CRITICAL: Change postgresql:// to postgresql+asyncpg://
  5. 5Go to Settings → API for SUPABASE_URL and SUPABASE_ANON_KEY
Visit Supabase

Step 2

Backend — Render

  1. 1New → Web Service → Connect GitHub repo
  2. 2Select Docker as environment
  3. 3Mirror all environment variables from Master Reference
  4. 4Deploy — copy the live URL for frontend config
  5. 5Enable Deploy Hook for CI/CD integration
Visit Render

Step 3

Frontend — Vercel

  1. 1New → Project → Connect GitHub repo
  2. 2Set Root Directory: frontend/localleadpro-dashboard
  3. 3Add VITE_API_BASE_URL (your Render backend URL)
  4. 4Add VITE_API_KEY (matching backend API_KEY)
  5. 5Add VITE_SITE_NAME (your desired brand name)
  6. 6Deploy — your dashboard is live!
Visit Vercel

Production

Cross-Platform Architecture

Decentralized architecture ensuring high availability and performance.

👤UserVercel FrontendReact + ViteX-API-KeyHeaderRender APIFastAPI + DockerSupabasePostgreSQLGroq AILlama 3BrevoSMTP

No Proxy Needed in Production

In production, the React app communicates directly with the Render API. The server/index.ts proxy is only for local development to bypass browser CORS constraints. Simply point VITE_API_BASE_URL to your Render URL.

Ready to automate your outreach?

Join thousands of freelancers using AI to discover and engage qualified leads.

Get Started Free
Cold ScoutCold Scout

AI-powered lead generation platform that discovers, qualifies, and engages local business leads at scale.

Product

PricingDocumentationLead DirectoryFree ScannerIntegrationsUse casesCompareChangelog

Resources

BlogGuidesFAQSupportAI agents (llms.txt)

Legal

Privacy PolicyTerms of ServiceRefund PolicyData Deletion

Community

GitHub RepositoryReport an IssueLinkedIn Page Sponsor

© 2026 Cold Scout. All rights reserved.

SitemapRobotsBuilt with precision