leads4less/README.md

# LocaleScope

LocaleScope is a React + Vite app for researching local markets, saving business results in Postgres, and reviewing 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`
   - Stripe env vars below if you want to test billing locally
3. Run the user frontend:
   `npm run dev:web`
4. Run the admin frontend (dedicated surface):
   `npm run dev:admin`

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`

## First Run Checklist

- [ ] Install dependencies: `npm install`
- [ ] Copy `.env.example` to `.env.local` and fill required keys: `DATABASE_URL`, `COOKIE_SECRET`, `GOOGLE_MAPS_SERVER_KEY`, `VITE_GOOGLE_MAPS_PLATFORM_KEY`, and Stripe keys if testing billing
- [ ] Run migrations: `npm run migrate`
- [ ] Set `ALLOW_ADMIN_BOOTSTRAP=true` and define `ADMIN_BOOTSTRAP_TOKEN`
- [ ] Start app web, admin web, API, and worker: `npm run dev:web`, `npm run dev:admin`, `npm run dev:api`, `npm run dev:worker`
- [ ] Visit the admin surface and create the first site admin
- [ ] Disable bootstrap after first admin creation: `ALLOW_ADMIN_BOOTSTRAP=false`
- [ ] Verify admin billing access at `/api/admin/billing/workspaces`

## First-run Admin Bootstrap

Bootstrap mode is only needed when no active application admin exists.

- The DB-backed `application_admins` table is the primary source of truth for app-admin access.
- `ADMIN_EMAILS` and `BILLING_ADMIN_EMAILS` are fallback allowlists during rollout.

1. Run migrations first: `npm run migrate`
2. Set `ALLOW_ADMIN_BOOTSTRAP=true` and `ADMIN_BOOTSTRAP_TOKEN` in your env file
3. Visit the dedicated admin surface, then create the first account in "Create first site admin" mode
4. After the first admin is created, set `ALLOW_ADMIN_BOOTSTRAP=false`

## Stripe Billing Setup

Stripe is now the active payments integration for self-serve subscriptions and one-time export packs.

Configure these server-side env vars to enable billing routes:

- `STRIPE_PUBLISHABLE_KEY`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `STRIPE_PRICE_STARTER_MONTHLY`
- `STRIPE_PRICE_STARTER_ANNUAL`
- `STRIPE_PRICE_GROWTH_MONTHLY`
- `STRIPE_PRICE_GROWTH_ANNUAL`
- `STRIPE_PRICE_PRO_MONTHLY`
- `STRIPE_PRICE_PRO_ANNUAL`
- `STRIPE_PRICE_EXPORT_PACK_10K`
- `STRIPE_PRICE_EXPORT_PACK_50K`
- `STRIPE_BILLING_PORTAL_CONFIGURATION_ID` optional
- `ADMIN_EMAILS` optional comma-separated allowlist for internal app-admin access (preferred)
- `BILLING_ADMIN_EMAILS` optional deprecated fallback allowlist used when `ADMIN_EMAILS` is unset

Notes:

- The internal catalog in `shared/billing/plans.ts` and `shared/billing/addons.ts` remains canonical. Stripe price IDs are environment-specific mappings only.
- Apply migrations before testing Stripe webhooks so `billing_webhook_events` exists: `npm run migrate`
- Enterprise stays on a manual sales/invoicing path and does not use self-serve checkout.
- Stripe lifecycle hardening now treats `past_due` subscriptions as a grace-window state before chargeable actions hard-block. The default grace window is 7 days.
- Billing return notices now appear on the account page for completed and canceled checkout flows.
- Internal billing support visibility is available through `/api/admin/billing/workspaces` for allowlisted admin emails.

## Admin Operations Runbook

Bootstrap/security hardening checklist after first-run admin setup:

- Set `ALLOW_ADMIN_BOOTSTRAP=false` and redeploy API.
- Rotate `ADMIN_BOOTSTRAP_TOKEN` and store it in your secrets manager.
- Ensure at least two active app-admin identities are configured.
- Prefer `ADMIN_EMAILS`; stop relying on deprecated `BILLING_ADMIN_EMAILS` fallback.

Support diagnostics starting thresholds:

- Failed webhooks: investigate when there are 5+ failures in 15 minutes or 20+ failures in 24 hours.
- Stale sync accounts: investigate when 10+ workspaces are stale for more than 24 hours.
- Repeated payment failures: investigate any workspace with 3+ `invoice_payment_failed` events in 7 days.
- Pending plan effective in past: investigate when count remains above 0 for more than 2 hours.

First-response sequence for repeated failures:

1. Open Admin Console diagnostics and capture affected workspace IDs.
2. Open each workspace detail and review recent timeline and webhook event history.
3. Verify Stripe webhook delivery status and replay failed events where safe.
4. Confirm billing sync recovers and anomaly counts return toward baseline.
5. Escalate with captured event IDs and workspace IDs if issues persist.

Safe mutation pilot:

- Admin Console now includes a constrained billing resync mutation.
- Required inputs: `workspaceId`, operational reason, and typed confirmation (`RESYNC`).
- Optional input: `ticketRef` for support/incident traceability.

## Docker Deployment

1. Copy `.env.example` to `.env` and set at least:
    - `DATABASE_URL` to the Compose database host, for example `postgres://postgres:YOUR_PASSWORD@db:5432/leads4less`
    - `POSTGRES_DB`
    - `POSTGRES_USER`
    - `POSTGRES_PASSWORD`
    - `WEB_PORT`
    - `ADMIN_WEB_PORT`
    - `APP_PORT`
    - `COOKIE_SECRET`
    - `GOOGLE_MAPS_SERVER_KEY`
    - `VITE_API_BASE_URL` (use `/api` when web/admin and API share a domain via the nginx proxy)
    - `VITE_GOOGLE_MAPS_PLATFORM_KEY`
2. Create the shared Docker network if it does not exist:
   `docker network create locale-all || true`
3. Build and start the full stack:
   `docker compose up --build`

The Compose stack starts PostGIS, waits for the database to become healthy, runs migrations automatically, and then starts the API, worker, user-web, and admin-web containers.
With the default `.env.example` values, the user app is exposed on `http://localhost:3000`, the admin app on `http://localhost:3001`, and the API on `http://localhost:4000`.

## App and Admin Surfaces

- User and admin UIs now run on separate frontend surfaces/build targets.
- The main app no longer links to or renders admin routes/tabs.
- Admin tasks live on the dedicated admin surface and continue using the same API/session auth.
- `APP_ORIGIN` should include both origins for CORS/session checks, for example: `https://localescope.com,https://admin.localescope.com`.

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

Notes:
- Raw postal source files and generated GeoJSON datasets under `db/rawdata/` and `db/datasets/postal/*.geojson` are ignored by git.
- The importer expects WGS84 lon/lat GeoJSON. If a source file is projected, re-export it to `EPSG:4326` before importing.

Observability commands:
- `npm run import:postal` logs progress every 500 features by default.
- `npm run build:postal-neighbors` logs per-country progress and final adjacency totals.
- `npm run check:postal` prints current postal area and neighbor counts from the database.

You can change the import log interval with `POSTAL_IMPORT_LOG_EVERY`, for example:
`POSTAL_IMPORT_LOG_EVERY=1000 npm run import:postal`

If you want to validate the current postal tables after an import or neighbor build, run:
`npm run check: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.