Lead Automation MVP

This repository contains a legal, human-in-the-loop lead generation and outreach assistant for B2B services. It is designed as a legitimate sales productivity tool for consulting, telecom and vendor sourcing, AI automation, affiliate partnerships, and commercial negotiation services.

What the MVP does

• Dashboard for total leads, hot leads, drafted emails, follow-ups due, and conversion pipeline.
• Lead database with company, contact, source, score, status, and next-action tracking.
• Transparent lead scoring based on company size, geography, industry fit, website quality, and service relevance.
• Personalised outreach draft generation in professional British English.
• Approval-first workflow: drafts are saved only and must be reviewed manually before any send.
• Follow-up tracking and recommended next actions.
• CSV and simple report exports.
• Deal Mode for creating paid outbound deal packs with structured placeholder leads and commercial recommendations.
• Premium deliverable features including branded PDF export, editable templates, client branding fields, and manual enrichment CSV import.
• Inbound-first revenue engine with public offer pages, consent-aware inbound capture, lead magnet delivery, nurture sequencing, and pipeline attribution metrics.

Architecture

• Frontend: Next.js 14 with React and TypeScript
• Backend: FastAPI with SQLAlchemy
• Database: SQLite for the MVP

Project structure

backend/
  app/
  tests/
frontend/
  app/
  components/
  lib/
.env.example
README.md

Setup

Recommended local toolchain:

• Node.js 20 LTS or newer
• npm 10 or newer
• Python 3.9+

1. Backend

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create a project-level .env from .env.example, then run:

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack
source backend/.venv/bin/activate
uvicorn app.main:app --app-dir backend --reload

Backend API docs will be available at http://localhost:8000/docs.

2. Frontend

Install Node dependencies in frontend/, then start the app:

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack/frontend
npm install
cp .env.local.example .env.local
npm run dev

The UI will be available at http://localhost:3000.

Deal Mode usage

1. Open http://localhost:3000/deal-mode.
2. Choose a template or use Custom.
3. Enter the deal pack name, target country, target industry, service offer, lead count, ICP notes, and optional client branding fields.
4. Click Create Deal Pack.
5. Open the saved pack and click Generate.
6. Review the executive summary, scoring logic, outreach angle, follow-up sequence, lead table, branding, and pricing.
7. Export the deliverable as CSV, report, or PDF.
8. If you have manually enriched leads, import them via CSV into the selected pack.

Create a paid client deliverable

Use Deal Mode as a commercial packaging flow:

1. Select the template closest to the client brief.
2. Add client name, logo URL, Prepared for, and Prepared by.
3. Generate the deal pack to create the first structured draft.
4. Import manually enriched leads if you have them.
5. Export the final deliverable as a branded PDF for the client.

3. Run both with one command

From the repository root:

npm install
npm run install:frontend
npm run dev

This expects the backend virtual environment to already exist at backend/.venv.

Environment variables

Project-level .env:

BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
DATABASE_URL=sqlite:///./backend/data/leads.db
FRONTEND_API_URL=http://localhost:8000

Frontend .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

You can create it with:

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack/frontend
cp .env.local.example .env.local

Database schema

Main table: leads

• company_name
• website
• country
• industry
• company_size
• contact_name
• contact_email
• linkedin_url
• lead_source
• lead_score
• score_summary
• website_quality
• relevance_notes
• services_of_interest
• status
• last_contacted_at
• follow_up_due_date
• recommended_next_action
• draft_subject
• draft_body
• follow_up_subject
• follow_up_body
• notes
• created_at
• updated_at

An explicit SQL version is available at docs/database-schema.sql.

Additional Deal Mode tables:

• deal_packs
• deal_pack_leads

Seed data

The backend bootstraps seed data automatically on startup using backend/app/seed_data.py.

This includes:

• sample operational leads
• a sample generated deal pack: UK Telecom Sourcing Pilot
• a premium demo deal pack: UAE AI Automation Consulting Pilot

Tests

Run backend tests:

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack
source backend/.venv/bin/activate
pytest backend/tests -q

Optional frontend validation after npm install:

cd /Users/arachchige.p/Documents/Codex/2026-04-24-you-are-my-senior-full-stack/frontend
npm run build

Basic frontend build checklist:

• npm install
• npm run dev
• npm run build
• Expected output:
  • local dev app available at http://localhost:3000
  • Deal Mode page loads successfully
  • npm run build completes without compile errors on a normal local Node/npm setup

Validation flow used in the product

• Leads are scored and explained immediately when created or updated.
• Draft generation never sends email.
• Follow-up suggestions are visible in the dashboard.
• Exports are user-triggered only.
• Deal Mode uses structured placeholder leads only and is ready for future enrichment APIs.
• PDF exports are branded as Little KK Growth Engine and prepared in British English.
• Public inbound capture only sends nurture emails when consent is present and live send is enabled.
• If SMTP is not configured, consented leads are captured safely and queued with a blocked reason.

Public inbound launch

Public endpoints:

• GET /api/public/offers
• GET /api/public/landing-page/{slug}
• POST /api/public/inbound-capture

Public frontend pages:

• http://localhost:3000/offers
• http://localhost:3000/offers/ai-automation
• http://localhost:3000/offers/lead-generation
• http://localhost:3000/offers/sales-crm-automation
• http://localhost:3000/offers/recruitment-agency-automation
• http://localhost:3000/offers/clinic-automation
• http://localhost:3000/offers/real-estate-automation
• http://localhost:3000/offers/telecom-tech-automation

Consent rules:

• if consent_checkbox=true and SMTP plus live send are enabled, the system sends:
  • lead magnet delivery
  • nurture email 1
  • booking invite
• if consent is missing, the lead is captured but marked as Reviewed Send Required
• if live send is disabled or SMTP is unavailable, the lead is captured and queued safely

Required env vars for production launch:

CORS_ALLOW_ORIGINS=https://your-frontend.example,https://www.your-frontend.example
PUBLIC_BASE_URL=https://your-frontend.example
BOOKING_URL=https://cal.com/your-team/strategy-session
OUTREACH_LIVE_SEND_ENABLED=true
OUTREACH_EMERGENCY_PAUSE=false
SMTP_HOST=smtp.your-provider.example
SMTP_PORT=587
SMTP_USERNAME=your-user
SMTP_PASSWORD=your-password
SMTP_FROM_EMAIL=hello@your-domain.example
SMTP_USE_TLS=true

Production deployment

1. VPS backend

cd /path/to/2026-04-24-you-are-my-senior-full-stack
python3 -m venv backend/.venv
source backend/.venv/bin/activate
backend/.venv/bin/pip install -r backend/requirements.txt
cp .env.example .env
uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8000

Recommended reverse proxy:

• point api.your-domain.example to the VPS
• terminate TLS with Nginx or Caddy
• proxy requests to 127.0.0.1:8000

2. Vercel frontend

Set the frontend project root to frontend/ and configure:

NEXT_PUBLIC_API_URL=https://api.your-domain.example

Deploy the Next.js frontend and connect:

• www.your-domain.example
• offers.your-domain.example if you want a dedicated public funnel host

3. Custom domain and CORS

Backend .env:

PUBLIC_BASE_URL=https://www.your-domain.example
CORS_ALLOW_ORIGINS=https://www.your-domain.example,https://your-domain.example

4. SMTP setup

OUTREACH_LIVE_SEND_ENABLED=false
OUTREACH_EMERGENCY_PAUSE=false
SMTP_HOST=smtp.your-provider.example
SMTP_PORT=587
SMTP_USERNAME=your-user
SMTP_PASSWORD=your-password
SMTP_FROM_EMAIL=hello@your-domain.example
SMTP_USE_TLS=true

Rollout order:

1. keep OUTREACH_LIVE_SEND_ENABLED=false
2. submit one consented test lead
3. verify queued fallback works
4. enable live send only after the sender is confirmed

5. Booking link setup

BOOKING_URL=https://cal.com/your-team/strategy-session

This link appears in:

• public offer pages
• lead magnet delivery
• nurture email
• booking invite
• inbound engine proposal flow

6. Smoke tests

Health check:

curl https://api.your-domain.example/api/health

Public offers:

curl https://api.your-domain.example/api/public/offers

Submit a test inbound lead:

curl -X POST https://api.your-domain.example/api/public/inbound-capture \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Test User",
    "company":"Launch Test Ltd",
    "email":"test@launch-test.example",
    "phone":"+441234567890",
    "website":"https://launch-test.example",
    "country":"United Kingdom",
    "industry":"AI automation consulting",
    "interest":"Free AI Deal Pack",
    "consent_checkbox":true,
    "consent_timestamp":"2026-04-25T09:00:00Z",
    "source":"launch-smoke-test",
    "landing_page_slug":"ai-automation"
  }'

7. Reverse proxy and process management

Examples included:

• deploy/nginx.conf.example
• deploy/Caddyfile.example
• deploy/systemd/little-kk-backend.service
• deploy/systemd/little-kk-worker.service

Security hardening included:

• .env and local env files are ignored in .gitignore
• SMTP password is used only for SMTP login and is never logged
• public inbound endpoints use Pydantic validation with field length checks and required consent flags
• production startup rejects wildcard CORS via CORS_ALLOW_ORIGINS=*

8. Scheduler placeholder

Future daily bot-run notes are in:

• deploy/SCHEDULER.md

Target endpoint:

• POST /api/auto-sell/run

Manual enrichment CSV format

CSV columns for Deal Mode import:

• company_name
• website
• country
• industry
• contact_name
• contact_email
• linkedin_url
• notes

Next-step roadmap

1. Add authenticated user accounts and role-based approval permissions.
2. Add inbox integrations for Gmail and Outlook with reply syncing, but keep send approval explicit.
3. Introduce activity history, notes timeline, and task ownership.
4. Add lead import from approved CSV uploads and CRM sync.
5. Add richer scoring with editable scoring weights and ICP templates.
6. Add approval queues and audit logs for compliant outreach workflows.
7. Add analytics for reply rates, meetings booked, and source quality.

Paid features to add later

• Multi-user workspaces and team permissions
• Gmail and Outlook draft sync
• CRM integrations with HubSpot, Salesforce, and Pipedrive
• AI-assisted account research summaries from approved data sources
• Custom lead-scoring templates by service line
• Sequenced follow-up playbooks with approval checkpoints
• Pipeline forecasting and revenue attribution
• White-label reporting for agencies and consultants

How to sell this

• £500 pilot: deliver one branded deal pack with targeting, scoring logic, placeholder or enriched leads, outreach angle, and PDF export.
• £1,500 monthly pipeline: refresh deal packs monthly, maintain lead quality, import enriched leads, and hand over ready-to-approve outbound packs.
• £3,000-£5,000 done-for-you setup: configure the full outbound operating system, templates, branded deliverables, and client-specific workflow.

Compliance position

• No scraping-heavy collection is included in this MVP.
• No automated bulk sending is included.
• No deceptive or bypass-based behaviour is included.
• A human must review outreach before any send.