Documentation

Quick start

Requirement: Python 3.8 or newer. Everything else installs itself.

1. Download the release ZIP and unzip it somewhere easy to find — your Desktop is fine.
2. Open Terminal in that folder.
3. Run:

   $ ./start.sh

4. Wait for:

   Ripple Lead Finder is READY  →  http://127.0.0.1:5000

5. Open the address it printed. Your browser usually opens it for you.

Rather not touch Terminal? Double-click start.command on a Mac or start.bat on Windows. Exactly the same thing.

What the first run does

Seconds, not minutes — the only dependency is Flask. Running it twice never starts a second copy.

• Finds Python and pip
• Installs Flask if missing
• Creates the databases and folders
• Downloads the Foundry template list
• Runs a health check and prints the result
• Starts the app and opens your browser

The status table

Every start prints this. It is the honest state of your machine, not a splash screen.

Ripple Lead Finder
────────────────────────────
App             READY
Database        READY
Foundry         CONNECTED
Catalogue       198 industries
Audit           READY
Ollama          OPTIONAL / OFF
────────────────────────────
Ripple Lead Finder is READY  →  http://127.0.0.1:5000

If something is missing it says which feature you lose, not which package failed:

Audit           OPTIONAL / OFF  request failed
! Website audits are off — the Foundry audit engine didn't answer. Everything else works.

The app still starts. Finding leads, writing messages and building Foundry links carry on working.

Stopping, restarting, syncing

./stop.sh stops only the process this app started, found by the id it recorded and confirmed against the port it is listening on. It will not go hunting for anything called "python" and kill it.

Windows: double-click start.bat, or run python bootstrap.py setup then python app.py. The .sh scripts are macOS and Linux only — we would rather say that than pretend.

Quick start

Settings & API keys

Everything is configured in the in-app Settings panel — no terminal, no environment variables, no restart.

Data sources

All five are free and need no API key.

Why OpenStreetMap and not Google scraping

• Terms of Service. Google's ToS prohibit automated scraping of search results.
• It doesn't survive real use. Google serves a CAPTCHA after a few dozen automated queries and then blocks the IP. A scraper that passes testing dies on day one.
• Unstructured. Search HTML changes constantly, so the parser breaks every few weeks.

OpenStreetMap is free forever, legal to reuse under the ODbL licence, globally covered, and — decisively — structured: website, phone, email, contact:instagram and opening_hours are real fields, so "has no website" is an exact filter rather than a guess.

Search modes

Closed-shop filter

A list full of shut businesses destroys your credibility on the first call. Two independent mechanisms prevent it.

Lifecycle tag rejection

Any element with a lifecycle prefix on any key is dropped: disused, abandoned, demolished, razed, removed, closed, was, old, historic. So disused:shop=bakery never reaches your list.

Explicit closure signals

• disused=yes, abandoned=yes, closed=yes
• shop=vacant (empty retail unit)
• any end_date tag
• opening_hours=closed or off

Lead scoring

The score answers one question: how easily can I reach this person today? It is not a quality or wealth estimate.

Worked example. A barber with phone, email, address, opening hours, a known operator and a check date of 2026-04 scores 40 + 30 + 5 + 10 + 5 + 10 = 100. A social-only listing scores 15. Both are real leads; the first is worth your morning.

Link verification

Social links in map data are often stale. During a search the top 50 leads' Instagram, Facebook and website links are checked live, twelve at a time.

When a handle is missing entirely, each lead offers one-click targeted searches: Find their Instagram, Find their Facebook, Google them and Google Maps, plus a link to the source OSM listing so you can audit the data.

Messages

Four types are generated per lead, personalised from that lead's real data, each with a copy button.

Objection handling in the call script

Currency by market

Quoting dollars to a UK barber signals you don't know their market, so prices adapt automatically across 12 zones.

Fifteen niche-specific pitch angles name a concrete pain and a concrete win per trade — hotels get "guests book through sites taking 15–20% commission", barbers get "walk-ins can't check prices before turning up" — so the message never reads generic.

Business brief

One click produces a full brief on the business that ends with a paste-ready prompt for any AI website builder. Find lead → copy brief → paste into an AI → deliver site.

Guardrails in the AI prompt: only stated facts may be used, unknowns must be marked unknown, no claiming to have visited the premises, no invented reviews or awards, no hype vocabulary.

Foundry links

Every lead gets two personalised demo links — a website and a matching admin dashboard — carrying that business's own name, phone, town, trade and your agency name. Each has its own copy button on the lead card, so you never paste the wrong one.

How the link is built

The five fields are joined with a pipe, UTF-8 encoded, then base64url encoded into a single ?d= parameter:

BusinessName|Phone|City|TradeSlug|AgencyName
        ↓  utf-8, then base64url (no padding)
https://foundry.ripplecheck.io/demo/barber/?d=VGhvcm50b24ncyBCYXJiZXJzfCs0NDc3MDA5MDAxMjN8TGVlZHN8YmFyYmVy

This is encoding, not encryption. The token is trivially decodable and is meant to be — it contains the business's own public name, town and phone. Its job is to survive being pasted into any messenger on earth, not to keep anything secret. Do not put anything private in it.

Manual link builder

For prospects you found outside the app — a walk-in, a referral, a DM — press Manual link in the header. Type the business name, trade, town and phone and both links build live as you type, with their own copy buttons and a Copy both. The output is byte-identical to what a real lead produces.

The same thing from a terminal:

python3 make_link.py "Cric8InNet" cricket-academy \
        --city Delhi --phone "+91-9999-30-5050" --kind both

Deploy order

The links only personalise once FOUNDRY-decoder.js is live on the Foundry site — that is the script that reads ?d= and writes the details into the page. Upload it there before sending any links, or prospects will see the generic template.

The free audit

Foundry's audit engine, wired into the lead panel. Nothing to install — it runs on their server, so the button works the moment the app opens.

Thirty-one deterministic rules across five categories. No AI and no third-party service, which is why the same site audited twice returns the same score. Nothing is stored: the report is generated live from the public page and disappears when the tab closes.

Scoring

Each check carries a weight based on how directly it costs money. A missing tap-to-call button outweighs a missing favicon, because one loses phone calls and the other loses nothing measurable. Failures are sorted by weight, so the top of the list is the thing to fix first — not the easiest thing, and not the thing that would sell the most work.

What the panel shows

• Score out of 100 and a letter grade, with a lead temperature — hot, warm or cold.
• Five category bars, each scored separately.
• The failing checks, worst first, each with why it costs them enquiries and what fixing it involves.
• An opening line written from their biggest problem, with a copy button.
• Two links to send — the read-only report and the priced proposal.

The two links

Currencies: USD INR GBP EUR AED. Plans: starter business software platform. Add-ons: care,content,photo,seo,ads.

Batch auditing

Shortlist, top 5 or top 10 from the toolbar. Requests are spaced roughly three seconds apart because Foundry runs on shared PHP hosting and a burst gets throttled or 508s. A failed audit never stops the run; that lead is simply left unscored.

Failure handling

The endpoint always returns HTTP 200 with an ok flag — the response body is read as text and parsed in a try/catch rather than assuming JSON, because a shared host under load returns an HTML error page, not JSON. Whatever comes back, the panel shows the reason and offers a retry.

A site that times out is real information, not a bug: a site that doesn't answer the audit engine isn't answering some of their customers either. That is a fair thing to open a conversation with.

Pipeline & export

• Shortlist. Star leads you intend to message. They pin to the top and are counted in the floating outreach panel.
• Stages. New → Contacted → Replied → Won / Lost, plus private notes per lead.
• Filters. Industry, country, stage, has phone, has email, has Instagram, has Facebook, verified-live social, owner known, fresh data only, shortlist only.
• CSV export. Every field including link-verification status and owner name.
• Persistence. Everything lives in a local leads.db. Re-running the same search never wipes your pipeline — existing leads are skipped, only new ones are added.

Responsible outreach

These rules protect your business, not just theirs.

API endpoints

The app is a local Flask server. Useful if you want to script against it.

The engine also runs standalone from the command line:

$ python3 engine.py "Bakery" "Porto, Portugal"
$ python3 engine.py "Dentist" "Warsaw, Poland"

Files & privacy

Privacy. Everything runs locally. The only outbound calls are to OpenStreetMap for business data and, only if you add a key, to your chosen AI provider. No telemetry, no accounts, no analytics.

Troubleshooting

License

Ripple Lead Finder is released under the MIT License, Copyright © 2026 Agrajeet Verma. You may use, modify, distribute and sell it, with attribution.

Questions or bugs: open an issue on GitHub or email team@ripplecheck.io.