leads4less/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [2026-05-25]

### Added
- Added migrations to enforce workspace membership roles as `owner`/`member` only and to introduce DB-backed application-admin identities with access-audit storage.
- Added centralized admin authorization and audit helpers so internal `/admin/*` routes can use one shared access check and log admin support activity.
- Added a first-run admin bootstrap flow with `/api/admin/bootstrap/status` and `/api/admin/bootstrap/claim` so the initial application-admin account can be claimed safely.
- Added `bootstrap-token` and `bootstrap-enabled` environment/config support, plus setup docs and operational checklist updates for first-run admin provisioning.
- Added authenticated UI admin-badge visibility by exposing `isAdmin` on shared session/auth payloads.

### Changed
- Replaced env-only billing-admin authorization with application-admin checks backed by database records, while keeping env allowlist fallback support for rollout safety.
- Updated account and workspace permission handling so only workspace owners can manage workspace settings, and admin tooling visibility is driven by the new app-admin identity.
- Updated environment and setup docs for Stripe keys plus the new preferred `ADMIN_EMAILS` allowlist variable (with `BILLING_ADMIN_EMAILS` retained as a deprecated fallback).
- Reorganized the pricing rollout tracker to reflect completed phases, deferred work, and the new app-admin and workspace-role migration milestones.
- Updated auth/session responses to include canonical admin-status checks so admin UI state stays consistent after refresh and login.
- Updated README and TODO planning docs for phased admin-console rollout and the first-run operational checklist.

## [2026-05-22]

### Added
- Added an authenticated `Account` page with editable profile settings, workspace details, usage summaries, and placeholders for upcoming billing and team management.
- Added workspace and workspace-membership schema foundations plus new account API endpoints so each user now has a default personal workspace for future company, billing, and team features.
- Added a shared billing catalog, entitlement policy helpers, and feature-gate logic for Starter, Growth, Pro, and Enterprise packaging so pricing and future subscription enforcement can share one source of truth.
- Added workspace-scoped billing foundation storage, repository/service layers, and add-on catalog definitions for billing accounts, usage periods, usage counters, purchases, and balances.
- Added backend entitlement enforcement for basic search and deep research routes using shared workspace billing state and reusable usage-cost estimation.
- Added workspace-readiness reference material plus billing-aware account usage, add-on, and upgrade surfaces to keep plan promises honest during the workspace migration phase.
- Added Stripe payments foundations with checkout, billing-portal, and webhook processing routes plus idempotent webhook event storage for subscription sync and export-pack fulfillment.
- Added billing lifecycle hardening data and support workflows, including Stripe sync metadata, grace-period support, workspace billing timeline events, and billing-admin workspace visibility endpoints.
- Added billing and revenue instrumentation via a shared analytics event pipeline, API/webhook event emitters, and an admin analytics summary endpoint for pricing conversion, quota pressure, churn, and expansion signals.

### Changed
- Normalized the product UI around shared design primitives for buttons, cards, alerts, tabs, and page shells to keep public, auth, research, results, dashboard, map, and account surfaces visually aligned.
- Refined the authenticated app for mobile with a phone-friendly top bar, bottom tab navigation, shorter inline research maps, touch-friendlier map gestures, and a mobile lead-card presentation in the dashboard while preserving desktop layouts.
- Rebranded public, auth, worker, and supporting documentation copy from `Leads4less` to `LocaleScope` and repositioned the product around local market intelligence and territory research.
- Expanded the pricing experience with monthly/annual plan toggles, interval-specific pricing cards, and a comparison table derived from canonical billing metadata.
- Bootstrapped existing and new workspaces into a pre-payments Starter billing state so usage tracking and enforcement can run before subscription automation exists.
- Updated dashboard, map, and results copy to describe saved businesses and research outputs instead of lead-focused terminology.
- Replaced account-page billing placeholders with Stripe-backed upgrade, add-on purchase, and billing-management actions while keeping enterprise on a manual sales path.
- Hardened entitlement enforcement to treat past-due subscriptions as grace-window access before blocking chargeable actions, with clearer lifecycle messaging in account and API responses.

## [2026-05-01]

### Added
- Added a multi-stage `Dockerfile` and `docker-compose.yml` for running the web app, API, worker, and PostGIS database as a local container stack.

### Changed
- Updated the Docker Compose deployment config to read app secrets and Vite build settings from environment variables, and added a `.dockerignore` to keep container builds leaner.
- Aligned the Docker Compose and example environment settings so local and deployment configs use the same variable names and document URL-encoded database passwords when needed.
- Simplified container deployment by adding a dedicated migration image and Compose startup ordering so the database becomes healthy, migrations run automatically, and the API, worker, and web services start afterward.
- Published the Docker web and API services to host ports so local Compose runs are reachable directly from the browser with configurable `WEB_PORT` and `APP_PORT` values.

### Fixed
- Fixed the Docker startup flow by passing required env validation into the migration container, bundling SQL migrations into the runtime image, and creating pg-boss queues before the worker starts consuming them.

## [2026-04-19]

### Added
- Added separate `Research` and `Results` workspaces so new runs and saved run browsing live in distinct flows while preserving bundled map selection.
- Added dedicated Basic and Deep Research results views, plus a public landing page and dedicated auth route for the unauthenticated experience.

### Changed
- Made Basic research map-first by requiring a dropped pin or current location, sending coordinate-based searches through the API, and cleaning up shared map presentation.
- Simplified shared Google Maps rendering by moving Basic, Deep Research, and result review maps onto the same cleaner visual style.

### Fixed
- Fixed local logout behavior so the session cookie is cleared consistently and optional session-id logout requests can remove the active server session record.

## [2026-04-12]

### Changed
- Improved local development networking by making API env loading work with `.env.local`, adding LAN-friendly API URL fallback behavior, and fixing development CORS handling.
- Fixed local research inserts so nullable Google Places coordinates no longer break business upserts.
- Improved postal data tooling with streaming imports, clearer CRS validation, progress logs, and a status command for checking imported areas and adjacency counts.

### Added
- Added postal-area import and adjacency build scripts for US ZIP/ZCTA and Canada FSA datasets.
- Added a dedicated `Deep Research` view with map pin placement, propagation preview overlays, batch history, and bundled map navigation.
- Added backend deep-research preview, batch creation, and batch detail APIs, reusing the existing research engine to create one child search per postal area.

### Removed
- Removed stale local metadata, placeholder postal seeding code, and leftover Supabase-era repository artifacts.

## [2026-03-27]

### Changed
- Migrated the app from a Supabase runtime to a local Fastify API with PostgreSQL, PostGIS, and cookie-based session auth.
- Reworked the research experience with the `Leads4less` branding, the renamed `Research` view, a top-form layout, and a filterable grid of research jobs.
- Added local API wiring for research, dashboard, and map flows while keeping selected-job map behavior and broader lead retrieval support.

### Added
- Added local backend scaffolding under `server/` for auth, health checks, search routes, database access, and worker startup.
- Added local database migrations and scripts under `db/`, including the first PostGIS-enabled schema and migration runner.
- Added shared app types and frontend API/auth helpers for the local stack.

### Removed
- Removed the Supabase browser client, Edge Function runtime, and Supabase migration artifacts from the active app stack.

## [2026-03-26]

### Added
- Initial Leads4Less app with React and Vite.
- Supabase-backed authentication, lead storage, and search job persistence.
- Research, dashboard, and map views for running searches, browsing leads, and visualizing results on Google Maps.