pguerrerox
cc00a439bf
Add a dedicated Deep Research view with postal-area preview overlays, batch execution, and bundled map results. Also add postal dataset import tooling and fix local API networking and research insert issues needed to support the new workflow.
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# Leads4Less
|
|
|
|
Leads4Less is a React + Vite app for finding local business leads, saving them in Postgres, and browsing them in dashboard and map views.
|
|
|
|
## Stack
|
|
|
|
- React 19 + Vite
|
|
- Local Fastify API + pg-boss worker
|
|
- PostgreSQL + PostGIS
|
|
- Google Maps Platform for browser maps and Places search
|
|
|
|
## Local App Setup
|
|
|
|
1. Install dependencies:
|
|
`npm install`
|
|
2. Copy `.env.example` to `.env.local` and fill in at least:
|
|
- `VITE_GOOGLE_MAPS_PLATFORM_KEY`
|
|
- `DATABASE_URL`
|
|
- `COOKIE_SECRET`
|
|
- `GOOGLE_MAPS_SERVER_KEY`
|
|
3. Run the frontend:
|
|
`npm run dev:web`
|
|
|
|
The local backend and scripts load both `.env` and `.env.local`, with `.env.local` taking precedence, so you can keep the full local setup in one file during development.
|
|
|
|
If you open the app from another machine on your LAN, set `VITE_API_BASE_URL` and `APP_ORIGIN` to that host instead of `localhost`. In development, the frontend also auto-rewrites a `localhost` API URL to the current browser hostname to make local-network testing easier.
|
|
|
|
## Local API Setup
|
|
|
|
1. Ensure PostgreSQL is running locally with PostGIS available.
|
|
2. Apply the local database migrations:
|
|
`npm run migrate`
|
|
3. Start the API:
|
|
`npm run dev:api`
|
|
4. Start the worker:
|
|
`npm run dev:worker`
|
|
|
|
## Database Layout
|
|
|
|
- `db/migrations/0001_local_core.sql` creates the local-first schema.
|
|
- `db/scripts/migrate.ts` applies migrations in order and records them in `schema_migrations`.
|
|
- `db/scripts/import-postal-areas.ts` imports US ZIP/ZCTA and Canada FSA polygons from local GeoJSON files.
|
|
- `db/scripts/build-postal-neighbors.ts` builds adjacency links for deep research propagation.
|
|
- `db/datasets/README.md` documents the expected postal dataset locations and property names.
|
|
|
|
## Postal Dataset Setup
|
|
|
|
1. Place your GeoJSON files in:
|
|
- `db/datasets/postal/us_zcta.geojson`
|
|
- `db/datasets/postal/ca_fsa.geojson`
|
|
2. Or override them with:
|
|
- `POSTAL_US_DATASET_PATH`
|
|
- `POSTAL_CA_DATASET_PATH`
|
|
3. Import and build adjacency:
|
|
`npm run seed:postal`
|
|
|
|
## Google Maps Requirements
|
|
|
|
Enable these Google Cloud APIs for the keys you use:
|
|
|
|
- Maps JavaScript API
|
|
- Places API
|
|
- Geocoding API
|
|
|
|
Use a browser-restricted key for `VITE_GOOGLE_MAPS_PLATFORM_KEY` and a server-side key for `GOOGLE_MAPS_SERVER_KEY`.
|
|
|
|
## Current Runtime Flow
|
|
|
|
1. The React app authenticates through the local Fastify API using cookie-backed sessions.
|
|
2. Search requests run through the local API and persist results in PostgreSQL.
|
|
3. The worker foundation is available for asynchronous job execution and deep research expansion.
|
|
4. The target architecture is fully local auth + Fastify routes + pg-boss workers + PostgreSQL/PostGIS.
|