`README.md`

58 lines
# HomesOnSpec.com

**Every new home. Every builder. One search. Verified from the source.**

Nationwide search + comparison platform for newly constructed homes: move-in-ready and
under-construction inventory, communities, floor plans, and incentives — permission-aware,
evidence-backed, and verification-labeled.

## Status

Stage 1–2 complete: working marketplace over synthetic demonstration inventory
(3 markets, 4 fictional builders, ~113 homes, all labeled DEMONSTRATION) plus a fully
proven ingestion pipeline (fixture adapter → snapshots → staged → validated → review →
published). Top-10 national builder acquisition in progress (source registry + recon).

## Run it

```sh
pnpm install
createdb homesonspec && psql -d homesonspec -c 'CREATE EXTENSION pg_trgm'
cp .env.example .env
pnpm db:migrate && pnpm db:seed
pnpm pipeline -- --adapter=meridian-homes-fixtures   # fixture pipeline e2e
pnpm dev:web     # consumer app  → http://localhost:3100
pnpm dev:admin   # admin app     → http://localhost:3101 (Basic Auth, BASIC_AUTH env)
```

Tests: `pnpm -r test` (unit) ·
`pnpm --filter @homesonspec/workers test:integration` (pipeline vs homesonspec_test) ·
`pnpm e2e` (Playwright, boots both apps).

## Architecture

pnpm monorepo — see `docs/architecture/ADRS.md` for the nine decision records.

```
apps/web       consumer Next.js app (:3100)   apps/admin   protected admin (:3101)
apps/workers   pipeline stages + CLI + pg-boss daemon
packages/      database (Prisma) · schemas (zod) · validation (rule engine) ·
               search · publisher (ONLY writer of published tables) · shared · shared-ui
collectors/    common adapter contract + per-builder adapters
fixtures/      raw HTML pages + hand-authored expected extraction records
docs/          product · data-rights (READ FIRST) · architecture · source-runbooks
```

**The invariant that matters:** crawlers never write published tables. Data flows
source → RawSnapshot → StagedRecord (+ per-field SourceEvidence) → deterministic
validators (ValidationEvent, verdict) → human review when flagged →
`@homesonspec/publisher` — the single bridge to consumer-facing inventory. Missing values
are null, never guessed; every published fact traces to evidence.

## Data rights

`docs/data-rights/POLICY.md` is binding: facts only by default, no media without
registry-recorded rights, no access-control circumvention, honest User-Agent, robots
respected, removal requests honored. Verification labels derive from how data was
collected and can never overstate it.