`README.md`

43 lines
# USRealEstate — national market explorer

Live: https://usrealestate.agentabrams.com (basic auth) · local: `npm run server` → http://127.0.0.1:9913

Free-data national U.S. residential market platform: market metrics + opportunity scoring for every
county/metro, per-property detail (13 sections) for covered counties, and a national broker registry
from state licensing rosters. No MLS licenses, no paid data vendors — every source is free/public
with provenance (`ingest_runs`) and fail-loud URL-drift detection.

## Stack
TypeScript + tsx + Express + Postgres (`usre`, socket). Frontend: vanilla HTML/JS in `public/`
(dark/gold house style, no build step). pm2 `usrealestate`, port 9913.

## Data sources ($0)
| Source | Metrics | Cadence |
|---|---|---|
| Redfin Data Center | sale price, inventory, DOM, sale-to-list, supply | monthly |
| Zillow Research | ZHVI, ZORI | monthly |
| Census ACS 5-yr | income, rent, population, vacancy (key required) | annual |
| FHFA HPI | house price index | quarterly |
| FEMA NRI v1.20 | climate risk scores | release |
| HUD FMR FY26 | fair market rents 0–4BR | annual |
| State licensing rosters | 1.5M brokers / 172k firms — FL TX NY CO CT IL DE | daily rotation (stalest first) |
| County parcels | 5.78M lots / 8 counties — LA (SQLite), NYC 5 boroughs + King WA + Cook IL (PG) | on demand |
| Firm websites | 190 crawled (Brave Search discovery), IDX detection, contacts | on demand |
| NYC MapPLUTO | owner + zoning + assessed values | PLUTO version |
| King County WA | **recorded deed sales** (price/buyer/seller) | weekly |

Full open-data source catalog is served at `/sources.html`.

## Commands
`npm run migrate` · `seed:regions` · `ingest:zillow|redfin|acs|fhfa|nri|fmr` · `derive` · `score` ·
`ingest:brokers -- <state>|all` · `refresh` (full monthly chain, cron day-25 03:30)

## Key invariants
- Scoring is deterministic (frozen snapshot + `score-config.json` weights); thin markets
  (pop<50k or <10 sales/mo) are scored but **excluded from rank**.
- Legacy CT counties (09001–09015) coexist with planning regions — Zillow/Redfin ship legacy,
  the choropleth GeoJSON has legacy shapes.
- Every grid page has sort + density controls persisted to localStorage (house rule).
- Deploy: rsync to Kamatera `/root/public-projects/nationalrealestate`; nginx vhost must
  `listen 45.61.58.125:443`; `parcel_source` rows must be inserted per environment.