leads4less/README.md

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.