# 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`

## 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/seed-postal-placeholder.ts` is a placeholder for ZIP/ZCTA and Canada FSA imports.

## 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.