Finds local businesses that have no website, researches them from public sources, and builds each one a demo site to open a sales conversation with.
A sub brand tool of HTPdevs.
New to this repo? Read this page, then run the quickstart below. It takes about five minutes and needs no API key.
| I want to | Go to |
|---|---|
| Understand what this is and run it once | This page |
| Use this without a terminal | ui/README.md |
| Research a prospect and write their page | docs/ENRICHMENT.md |
| Know what every field in a prospect file means | docs/PROSPECT-SCHEMA.md |
| Add a new trade, for example roofing or dental | docs/ADDING-AN-INDUSTRY.md |
| Fix something that broke | docs/TROUBLESHOOTING.md |
| Work on the CLI itself | cli/README.md |
| Work on how the demo sites look | demos/README.md |
A large number of small local businesses have real customers, years of good reviews, and no website. Their entire online presence is a Google listing and a few directory pages they never look at.
That is a sales opening. Rather than cold pitching, we build the business a real demo site first, using facts already public about them, and lead with it. The conversation starts at "here is your site" instead of "would you like a site".
HTPfinder is the machinery for doing that repeatably across any trade.
Three stages. The middle one is a person or an agent doing research, and that is deliberate rather than a gap waiting to be filled.
1. COLLECT 2. ENRICH 3. BUILD
---------- --------- --------
Google Places API -> research and judgment -> demo site
script agent, then validate script
Who has no website? Who are they, really? Show them.
Collect is cheap and mechanical. One API call per search phrase returns name, phone, address, rating, review count, hours, and crucially whether the business has a website at all. Everything failing the website check becomes a prospect file.
Enrich is where the value is. Google Places gets you roughly sixty percent of what a good page needs. The rest, years in business, crew size, owner name, payment methods, the actual service list, lives on trade directories, and pulling it together takes judgment. Deciding that two sources disagreeing about an address means omitting the address, or that a perfect rating stranded on a directory nobody visits is the real sales hook, is not something a scraper produces. docs/ENRICHMENT.md is the procedure.
Build is mechanical again. A validated prospect file becomes the renderer's data files, and the demo site exists.
These pages carry a real business's name and get shown to that business's owner. So:
Every factual claim on a demo page traces to a public source URL recorded in the prospect file. A fact we cannot source is
null, never a guess.
That is not a style preference, it is the thing that keeps this from being spam. A page that invents a testimonial, a certification, or a years in business number is worse than no page at all, because the owner will notice and the conversation is over.
The layout degrades around missing facts rather than filling them in. No phone number means the page drops the call action everywhere and leads with a form. No public review text means the reviews section shows the real aggregate scores with an honest note, never a written testimonial nobody left.
htpfinder validate enforces this mechanically. Read
docs/PROSPECT-SCHEMA.md for exactly what it checks.
Every demo also carries a visible preview ribbon and a footer disclaimer saying it is an unaffiliated concept preview. Leave both in place.
Needs Node 20 or newer. No API key required for this walkthrough, which runs against recorded results.
cd apps/htpfinder/cli
npm test # no dependencies to install
# What trades does this install know about?
node bin/htpfinder.js industries
# Find prospects. --fixture replays recorded Places results.
node bin/htpfinder.js collect lawn-care --fixture portland-lawn-care.places.json
# What did we get?
node bin/htpfinder.js list
# Look at one in detail, with its sources
node bin/htpfinder.js show key-concepts-landscape
# Write the copy straight from the collected facts, no agent involved
node bin/htpfinder.js enrich --all
# Or get the research brief, for the prospects worth a call
node bin/htpfinder.js packet key-concepts-landscapeThe collect output ranks prospects by score and explains, per business, why
it thinks there is no website. Businesses that turn out to have a working site
are skipped and counted.
Or do all of that in a browser instead:
cd ../ui && npm install && npm run build # once
cd ../cli && node bin/htpfinder.js uiThe control panel runs the same code underneath and shows the command behind every action, so it is also a way to learn the CLI.
To run against live data instead, set a key and drop the fixture flag:
export GOOGLE_PLACES_API_KEY=...
node bin/htpfinder.js collect auto-repair --near "Portland, OR" --limit 50Prospects collected from a fixture are marked as such and cannot be built into a page. That is intentional: fixture ratings are placeholders, and placeholder data must never reach a page carrying a real business name.
Two demos are already researched and committed. To view one:
cd apps/htpfinder/demos
npm install
VITE_DEMO=key-concepts-landscape npm run devBoth were generated from their prospect files, so cat either of
data/prospects/*/prospect.json to see exactly what a finished input looks
like before writing your own.
apps/htpfinder/
README.md this file
docs/ the guides linked at the top
htpdevs-business-plan.md
cli/ the tool
industries/ one file per trade, all vertical specific config
fixtures/ recorded Places responses, for offline work
src/commands/ one file per CLI command
src/lib/ places, qualify, palettes, schema, validate
test/
data/prospects/<slug>/
raw.json verbatim Places response, never edited
prospect.json the contract: sourced facts plus written copy
demos/ the renderer
src/data/<slug>/ GENERATED from prospect.json, do not hand edit
src/components/ the shared page sections
Files are the working surface, so a pass is inspectable with cat and a bad one
is undone with rm. The enrichment step is an agent filling in a file, and that
does not want a database in the middle.
Supabase is where the result lives afterwards, because it can scope rows to
their owner and it can actually delete, which a git history cannot.
htpfinder sync push and htpfinder sync pull move between the two. Schema and
reasoning in supabase/README.md.
data/ is gitignored, and that is deliberate. A prospect file carries an owner
name, a direct phone and an address, and for a sole proprietor the last two are
routinely a personal cell and a home address. Add verbatim review quotes from
named third parties and the file is a targeting list built on personal data,
which is not something to make permanent in a history that might one day be
pushed somewhere public. Losing the between-passes diff is the price.
raw.json would be out anyway: it is the verbatim Places response, and Google's
terms restrict storing Places content.
Do not hand edit anything in demos/src/data/<slug>/. Those files are
generated. Edit the prospect file and run htpfinder build <slug> again.
Editing the generated file breaks the chain between a claim on the page and the
source it came from, which is the one thing this system exists to preserve.
Every generated file says so at the top.
Do not copy another trade's industry profile without redoing the research. The directory list and the review thresholds are the two settings that quietly make the tool bad at a trade if they are wrong. Twelve reviews is a healthy lawn crew and a struggling auto shop. docs/ADDING-AN-INDUSTRY.md covers this.
Working: collect, the qualifier, scoring, the prospect schema and validator, the palette system, build, and the renderer. Two industry profiles, lawn care and auto repair. Two finished demos.
Not built yet: htpfinder enrich calling the Claude API directly so the middle
stage runs unattended, and the Google Sheets export. The schema and the packet
exist so that first one is a mechanical addition once output quality is proven.
Automating it before then risks discovering later that the pages read generic.
Demo sites stay local at localhost unless specifically decided otherwise.