| # LeadGen — Step-by-Step Guide (Personal Tool by AJ) |
|
|
| > Single-owner India SMB finder: Maps → no-website hunt → scoring → AI icebreakers → Sheets. No bulk sending from this server. |
|
|
| --- |
|
|
| ## 1) What you need before you start |
| - A Gmail account (owner — this will be the *only* login allowed via `APP_ALLOW_EMAIL`) |
| - A Hugging Face account (for the Space at `https://abc1181-leads.hf.space`) |
| - Optional but recommended: a Google Cloud project (for Places + OAuth) — free tier is enough |
|
|
| --- |
|
|
| ## 2) Create the Hugging Face Space |
| The code is already pushed to `abc1181/Leads` (Docker). Just configure envs: |
|
|
| 1. HF → Space `abc1181/Leads` → **Settings → Variables** (non-secrets) and **Secrets** (tokens) |
| 2. Set the essentials below (Section 3). The Space auto-restarts on save. |
| 3. Check `https://abc1181-leads.hf.space/api/health` → should be `{"ok":true,"db":"ok","persistence":"on"}`. If `persistence:off`, the Space has no `/data` bucket — it will still run on ephemeral `/tmp` (banner shows), but add a bucket at `/data` in Space Settings for durability. |
|
|
| --- |
|
|
| ## 3) Env vars — what to create |
|
|
| ### 3.1 Essentials (app won't work without these) |
| Set in HF **Variables** unless marked **Secret**: |
|
|
| | Key | Where | Value / How | |
| |---|---|---| |
| | `APP_ALLOW_EMAIL` | Variables | Your Gmail exactly — only this can sign in (`middleware.ts:39`, `lib/auth.ts:14`) | |
| | `GOOGLE_CLIENT_ID` | Variables | From Google Cloud OAuth (see 4.1) | |
| | `GOOGLE_CLIENT_SECRET` | **Secrets** | Same OAuth client | |
| | `NEXTAUTH_SECRET` | **Secrets** | Random 32b hex: `openssl rand -hex 32` (already set) | |
| | `NEXTAUTH_URL` | Variables | `https://abc1181-leads.hf.space` (already set) | |
| | `PLACES_API_KEY` | **Secrets** | Google Places API key (see 4.2) — *or leave empty and use the free OSM/Ola rail (Section 4.3)* | |
|
|
| Also needed (already set, don't change): `DATABASE_URL=file:/data/leads.db`, `CRON_SECRET`, `ENCRYPTION_KEY` |
|
|
| ### 3.2 Optional — add when you want more coverage |
| | Key | Where | Free tier | Notes | |
| |---|---|---|---| |
| | `OLA_API_KEY` | Secrets | 100k/API/mo free | India best free — `docs/maps-providers.md#5` | |
| | `MAPPLS_CLIENT_ID` + `MAPPLS_CLIENT_SECRET` | Secrets | Free eval, no card | India best address hit — `docs/maps-providers.md#4` | |
| | `FOURSQUARE_API_KEY` | Secrets | 500 free calls | Global fallback | |
| | `HERE_API_KEY` | Secrets | ~5k-250k free (needs card) | Global fallback | |
| | `ENRICH_PROVIDER=hunter` + `ENRICH_API_KEY` | Secrets | 25-50/mo free | Else phone is spine, emails stay `unknown` | |
| | `LLM_BASE_URL` + `LLM_API_KEY` + `LLM_MODEL=mistral-large-latest` | Secrets | Your gateway | Else fallback templates (`lib/ai/fallback.ts`) | |
| | `SMTP_HOST/PORT/USER/PASS` **or** `RESEND_API_KEY` + `DIGEST_TO` | Secrets/Vars | 100/d free | Else digest is in-app only | |
| | `MOCK_SOURCES=1` | Variables | — | Use for demo with 50 Delhi fixtures, no keys | |
|
|
| > **No billing?** Leave `PLACES_API_KEY` empty — the 6-provider rail (`lib/sources/maps.ts`) runs on **OSM Overpass (free, no key)** + `OLA_API_KEY`/`MAPPLS_*` if you set them. Add Google later and it stacks — no rebuild. |
| |
| --- |
| |
| ## 4) How to get each credential |
| |
| ### 4.1 Google OAuth (for Sign-in + Sheets) |
| 1. https://console.cloud.google.com → Create project → **APIs & Services → OAuth consent screen** → External → fill App name, Support email → Save |
| 2. **Credentials → Create Credentials → OAuth client ID** → Web application → Authorized redirect URI → add: `https://abc1181-leads.hf.space/api/auth/callback/google` → Create → copy **Client ID** and **Client Secret** → paste to HF as above. |
| |
| ### 4.2 Google Places API (New) — $200 free, needs billing |
| 1. Same Cloud project → **APIs & Services → Enable APIs** → search **Places API (New)** → Enable |
| 2. **Credentials → Create Credentials → API key** → Restrict → API restrictions → **Places API (New)** only → Save → copy to `PLACES_API_KEY`. |
| 3. Enable billing (Billing → Link account) to get the $200 credit — you won't be charged inside free. Our use ≈ $5-10 (`lib/sources/places.ts:50` caps to 60 + Details only for no-website). Quota bar turns amber at 80% and degrades to `partial`. |
| |
| ### 4.3 Free India maps (no billing) — Mappls + Ola |
| - **Mappls:** https://www.mapmyindia.com/api → Sign up → Dashboard → Create project → If you have a **Static/REST key** (your case), set `MAPPLS_API_KEY`; if you have OAuth pair, set `MAPPLS_CLIENT_ID` + `MAPPLS_CLIENT_SECRET` — either works. Free eval, no card. |
| - **Ola Maps:** https://maps.olakrutrim.com → Sign up (Krutrim Cloud) → Credentials → API Key → `OLA_API_KEY`. 100k/API/mo free from 2026-09-01. `GET https://api.olamaps.io/places/v1/nearbysearch?location=lat,lng&radius=&keyword=` header `X-API-KEY`. |
| |
| ### 4.4 Other free maps (optional) |
| - **Foursquare:** foursquare.com/developers → My Apps → Create App → API Key → `FOURSQUARE_API_KEY` (500 free). |
| - **HERE:** developer.here.com → Project → API Key → `HERE_API_KEY` (needs card, pay-as-you-grow). |
| - **OSM Overpass:** No key. Always on at `https://overpass-api.de/api/interpreter`. |
| |
| Full per-provider table: `docs/maps-providers.md`. |
| |
| ### 4.5 Enrich (emails, optional) |
| - Hunter: hunter.io → API key (25 free) → `ENRICH_API_KEY` with `ENRICH_PROVIDER=hunter` |
| - Apollo: app.apollo.io → API key (50 free) → `ENRICH_PROVIDER=apollo` |
|
|
| ### 4.6 LLM (AI drafts, optional) |
| Any OpenAI-compatible gateway. Set `LLM_BASE_URL` (e.g. `https://api.mistral.ai/v1`), `LLM_API_KEY`, `LLM_MODEL=mistral-large-latest`. **Llama banned** on any provider (`lib/ai/llm.ts:44` — AUP). Prompts are PII-free (`lib/ai/prompts.ts:8`). |
|
|
| ### 4.7 Email digest (optional) |
| - Gmail: App Password → `SMTP_HOST=smtp.gmail.com`, `SMTP_PORT=587`, `SMTP_USER`, `SMTP_PASS`, `DIGEST_TO=you@gmail.com` |
| - Resend: resend.com → API key → `RESEND_API_KEY` (100/d free) |
|
|
| --- |
|
|
| ## 5) Run locally (optional) |
| ```bash |
| cp .env.example .env.local # fill with your keys; use absolute DATABASE_URL |
| # MUST be absolute locally (Prisma CLI vs app resolve differently): |
| # DATABASE_URL="file:/abs/path/to/leads-app/data/leads.db" |
| npm install --registry https://registry.npmjs.org/ |
| npx prisma migrate dev # creates data/leads.db |
| npm run dev # http://localhost:7860 |
| npm test # 59 unit (lib 80% lines) |
| # integration (mock): INTEGRATION=1 MOCK_SOURCES=1 DATABASE_URL="file:$PWD/data/test.db" npx vitest run |
| ``` |
|
|
| --- |
|
|
| ## 6) How to use the app (morning loop) |
| 1. **Searches → New search** → pick template (Health/Beauty, Food, B2B/Factory, MidMarket/Upgrade, Generic) → city + radius (geocoded & cached, `lib/geo.ts:4`) → keywords → Cap 20/50/100/200 → Create. Star it for nightly. |
| 2. **Run search** → progress header (per-provider ms/quota) → tabs Hot/Warm/Cold (`lib/score.ts:65` threshold) → table (filter by status/source/email/band/phone, sort score/rating) → drawer (AI draft violet, Copy/Regenerate, notes, blocklist). |
| 3. **Verify all** (concurrency 5, skips fresh <7d unless forced) → **Push to Sheets** (master `LeadGen Master`, tab per search, 21 cols, idempotent on email→phone→company|location via `lib/sheets.ts:rowKey`) → **CSV fallback** per run. |
| 4. **Hot queue (`/hot`)** is the morning inbox — `j/k` move, `q` qualify, `c` copy icebreaker, `?` help. |
| 5. **Dashboard** shows Hot/Warm/Cold donut, per-source yield, category intel (`Where the buyers are`), quotas ($0), recent runs. Bell shows unread Hot + quota warnings. |
| 6. **Settings** → Quotas, Keys presence (masked), Scoring weights + Re-score, Templates, Sheets connect/disconnect (OAuth sealed `lib/crypto.ts`), Blocklist (undo), Danger (purge caches). |
|
|
| **Nightly:** GitHub Actions `30 20 * * * UTC` (02:00 IST) pings `/api/health` 5× then `POST /api/cron/nightly` with `CRON_SECRET` (`jobs/runner.ts:38` sequential, `roles` rolled if >25min). Digest top-10 Hot to `DIGEST_TO` (self only) + in-app bell. |
|
|
| --- |
|
|
| ## 7) Troubleshooting |
| - `https://abc1181-leads.hf.space/api/health` → `ok:true, db:ok, persistence:on` means good. `persistence:off` = no bucket at `/data` — still runs on `/tmp` but data resets on restart (banner shows). |
| - Sign-in 500 → `GOOGLE_*` or `APP_ALLOW_EMAIL` wrong, or redirect URI not set to `https://abc1181-leads.hf.space/api/auth/callback/google`. |
| - Search returns 0 / `partial` → check quota bars in Settings; with no keys, OSM/Ola still work if those keys are set. |
| - Chrome "Deceptive site" → fixed in `c029112` by making `/`, `/privacy`, `/terms` public (no auto-Google redirect). If still cached, request review at https://transparencyreport.google.com/safe-browsing/search?url=https://abc1181-leads.hf.space |
|
|
| --- |
|
|
| ## 8) Branding & cost |
| - Branding: **Made by AJ · personal tool** (sidebar/footer/landing, `components/app-shell.tsx:39`). No Vercel triangle. |
| - Cost: $0 target (`docs/runbook.md`). Quota bars prove it. 80% banners + auto-degrade, never spend. |
|
|
| Questions? See `PRD.md`/`TRD.md` checkboxes (210 ticked, 52 intentionally unticked for live/V1.1/V2/parked). |
|
|
