Local Business Lead Engine

What it is

Local Business Lead Engine is a provider-agnostic research and qualification tool for finding local businesses, checking their public digital presence, discovering public contact details, and surfacing potential digital-service opportunities for human review. It is available as a CLI and as a small local web application.

The problem and business value

Local-market research often starts with scattered provider results and manual website checks. This project turns that work into a repeatable pipeline: business records are normalized and deduplicated, public websites are checked against consistent signals, and each record receives transparent reasons for its opportunity score. The intended value is faster, more consistent review of candidates for website, SEO, performance, booking, maintenance, and related digital-presence work. The repository does not contain evidence of customer adoption, revenue, or realized sales outcomes.

What it does today

• Accepts a category or business query plus a location, coordinates, radius, result limit, and enrichment options.
• Uses a deterministic Mock provider for local testing and an implemented Google Places API (New) adapter for Text Search and Nearby Search.
• Normalizes provider records and deduplicates them using provider identity where available, with a normalized business fallback.
• Inspects a public homepage and a bounded set of same-origin contact, booking, about, or team pages.
• Detects reachability, HTTPS, title and metadata, mobile viewport, contact and booking signals, structured data, social links, response time, and lightweight technology signals.
• Extracts public emails and phone numbers with source URLs and confidence values, then applies transparent rule-based opportunity scoring with HIGH, MEDIUM, and LOW buckets.
• Persists searches and normalized leads in SQLite, caches derived website analysis, saves checkpoints, and exports CSV and JSON results.
• Provides a local browser UI plus a versioned v1 HTTP boundary for health, asynchronous search creation, job polling, and saved-lead filtering.

The current provider result window is not a guarantee of complete city coverage. Provider ranking, geographic interpretation, pagination, quotas, and result caps still apply.

Integrations and data flow

The source boundary currently supports the deterministic Mock provider and Google Places API (New). The Google connector is implemented, but live use still requires a provider key, an enabled and billed Places API project, quota and cost decisions, terms/retention review, and a production validation run.

The main flow is:

provider discovery
  → normalization and deduplication
  → bounded public website analysis
  → public contact discovery
  → rule-based opportunity scoring
  → SQLite lead/search state
  → CSV/JSON exports and UI/API results

The local HTTP contract is designed as an integration boundary for a future OpportunityOS/Supabase adapter. OpportunityOS/Supabase code, workspace permissions, and end-to-end synchronization are not implemented in this repository.

AI or automation workflow

There is no generative AI, AI-written brief, or AI chat assistant in the current codebase. Website intelligence and opportunity qualification are deterministic and rules-based. Automation is used for asynchronous search execution, bounded concurrency, retries with backoff, checkpointing, cache reuse, stale-worker recovery, and partial-result retention. A person still reviews the evidence and decides what to do with a lead; the workflow is not autonomous sales outreach.

Lead, email, notification, or collaboration flow

A discovered business becomes a normalized lead, can be linked to multiple searches, and is returned through the local UI/API or exported as CSV/JSON. Public email and phone discovery is limited to inspected public HTML and mailto:/tel: links; the system does not guess personal addresses or send outreach emails. Job status is exposed through asynchronous polling and persisted state, with no notification service or collaboration/chat workflow in this repository. The UI is a search-and-results surface, not an owner-replied chat or automatic assistant.

Security/privacy boundaries

• Website inspection accepts only HTTP(S), resolves and rejects private or metadata networks, re-checks redirect targets, limits redirects and HTML size, enforces timeouts, and ignores non-HTML responses.
• The system does not bypass authentication, CAPTCHAs, rate limits, provider controls, or use proxy-rotation/stealth tooling.
• Contact discovery reads public pages only and retains provenance and confidence for review. Raw provider payloads are not persisted by default; local storage keeps normalized snapshots, enrichment history, search state, cache entries, and checkpoints.
• Provider credentials stay server-side. When an internal secret is configured, non-health API routes require the server-to-server secret and error/log paths redact sensitive values. Preview and production configuration also require an HTTPS hosted URL and persistent storage decisions.
• Provider terms, attribution, retention, quota, and commercial-spend rules remain owner responsibilities before live or commercial use.

What is coming next

The documented next steps are operational verification and scale: deploy the service privately with persistent storage and a clear single-worker/shared-queue policy; validate Google Places configuration, quota, terms, and cost; run the hosted mock-safe smoke check; and complete the OpportunityOS-side integration.

Product direction includes an area-coverage planner that searches bounded overlapping cells, reports request/cost/coverage signals, and resumes child searches; additional legitimate providers such as OSM/Overpass; and an OpportunityOS experience for protected integration settings, background synchronization, Location Leads, detail views, workspace permissions, and explicit CRM linking. None of those future capabilities should be read as shipped here.

Current activity or evidence from the project

The repository currently contains one initial commit dated 2026-08-26, so there is no long-term activity history or external adoption evidence to report. At inspection time, the local release gate passed: 10 test files and 28 tests passed, along with TypeScript type checking, linting, formatting validation, and a production build.

The tests cover provider mapping and deterministic mock data, normalization and deduplication, public website signals and URL safety, scoring, exports, the end-to-end mock pipeline, worker retry/recovery/partial results, and the HTTP contract including authentication, validation, request correlation, asynchronous jobs, and lead filters. Live Google Places access, hosted deployment, production spend/quotas, complete city coverage, and OpportunityOS end-to-end synchronization were not verified in this repository.