Contractor Trust Hub

Before you hire, verify.

Independent, evidence-backed contractor verification for homeowners and commercial buyers. Phase 0 establishes the data foundation: state license extracts, entity linkage, discipline, and a transparent trust-score schema.

Status	Florida Verify live; Texas Verify v1 (TDLR); Oregon CCB; Washington L&I; Arizona ROC; New Jersey Verify pilot (HIC + specialty)
Repo	https://github.com/savitz25/contractor-trust-hub
Primary market (wave 1)	Florida (DBPR Construction Industry Licensing Board)
Texas	TDLR specialty trades only — no statewide GC license (see docs/TEXAS_VERIFY_V1.md)
New Jersey	HIC + specialty boards only — no statewide GC license (see docs/NEW_JERSEY_VERIFY_V1.md)
Oregon	Statewide CCB explore + verify (see docs/OREGON_FULL_JOURNEY_V1.md)
Washington	Statewide L&I contractor licenses (see docs/WASHINGTON_VERIFY_V1.md)
Arizona	Statewide ROC explore + verify (see docs/ARIZONA_FULL_JOURNEY_V1.md)
Tagline	Before you hire, verify.

Product positioning

• Educational / research tooling — not a substitute for official licensing boards
• Every metric sourced (state board, Sunbiz, permits, discipline dockets)
• Prefer precision over thin profiles
• No invented licenses, NMLS-style guesses, or unverified “ratings”

Repository layout

contractor-trust-hub/
├── app/                     # Next.js product shell (Vercel)
├── docs/
│   ├── DATA_SOURCES.md      # FL DBPR, Sunbiz, TX, OR, WA, NJ index
    │   ├── DATA_SOURCES_TX.md   # Texas TDLR specialty (no statewide GC)
    │   ├── DATA_SOURCES_NJ.md   # NJ DCA HIC + specialty (no statewide GC)
    │   ├── DATA_SOURCES_OR.md   # Oregon CCB statewide
    │   ├── DATA_SOURCES_WA.md   # Washington L&I statewide
│   ├── PHASE_0.md
│   └── SCHEMA.md
├── schema/
│   └── initial_schema.sql
├── ingest/                  # Python offline adapters (not a Vercel Python app)
│   ├── requirements.txt
│   └── adapters/{fl_dbpr,tx_tdlr,nj_dca}.py
├── data/samples/
└── scripts/download_{fl_dbpr,tx_tdlr,nj_dca}.py

Quick start (web — Verify product)

npm install
# .env.local must include DATABASE_URL (Supabase Session pooler) — see docs/SUPABASE.md
npm run dev    # http://localhost:3000
npm run build  # production build (what Vercel runs)

Route	Purpose
/	Homepage + search CTA
/verify	Florida search by license or name
/verify?state=tx	Texas TDLR specialty trades (honest coverage banner)
/verify?state=nj	New Jersey HIC + specialty boards (honest coverage banner)
/verify?state=or	Oregon CCB statewide licenses (honest coverage banner)
/oregon	Oregon explore (official county / project)
/verify?state=wa	Washington L&I statewide licenses (honest coverage banner)
/verify?state=az	Arizona ROC statewide licenses (honest coverage banner)
/arizona	Arizona explore (county / city / project)
/contractors/[slug]	Trust Report (FL / TX / NJ / OR / WA / AZ by home_state)
/about · /methodology	Trust / transparency

See docs/VERIFY_PRODUCT.md.

Vercel: framework Next.js (vercel.json). Set DATABASE_URL (Supabase Session pooler, sensitive) and optionally NEXT_PUBLIC_SITE_URL. See docs/VERIFY_PRODUCT.md. Python under ingest/ is offline tooling only.

Search indexes (once per database):

psql "$DATABASE_URL" -f schema/migrations/002_search_indexes.sql

Quick start (ingest)

pip install -r ingest/requirements.txt

# Optional: fetch the full official construction licensee extract (~47 MB)
python scripts/download_fl_dbpr.py

# Normalize sample (or full file) → data/staging/fl_dbpr/
python -m ingest.adapters.fl_dbpr --input data/samples/fl_dbpr_construction_licensees_sample.csv --has-header
# Full extract (no header row):
python -m ingest.adapters.fl_dbpr --input data/raw/fl_dbpr/CONSTRUCTIONLICENSE_1.csv

Quick start (Postgres load)

# Requires DATABASE_URL or PG* env vars — see docs/LOAD_PATH.md
python scripts/load_fl_dbpr_to_postgres.py --init-schema --staging-dir data/staging/fl_dbpr
python scripts/verify_fl_dbpr_load.py

Quick start (Texas TDLR specialty — Verify v1)

# Open data SODA 7358-krk7 — specialty contractor types only
python scripts/download_tx_tdlr.py
python -m ingest.adapters.tx_tdlr \
  --input data/raw/tx_tdlr/tdlr_licenses_specialty.csv \
  --out-dir data/staging/tx_tdlr
python scripts/load_tx_tdlr_to_postgres.py --staging-dir data/staging/tx_tdlr

Product: /verify?state=tx. Coverage rules: docs/TEXAS_VERIFY_V1.md.

Quick start (Sunbiz entities + linker)

# Official public SFTP — see docs/SUNBIZ.md
python scripts/download_sunbiz.py --daily-latest
python -m ingest.adapters.fl_sunbiz \
  --input data/raw/sunbiz/daily \
  --glob '*c.txt' \
  --out-dir data/staging/fl_sunbiz

# Load + high-confidence DBPR links (requires DATABASE_URL)
python scripts/load_sunbiz_to_postgres.py --init-schema --staging-dir data/staging/fl_sunbiz
python scripts/link_dbpr_to_sunbiz.py
python scripts/verify_sunbiz_link.py

Phase 0 goals

1. Document exact public data sources and field layouts
2. Define Postgres schema (contractors, licenses, entities, permits, discipline, trust scores)
3. Ship first concrete adapter: Florida DBPR Construction
4. Keep raw downloads out of git; commit samples + profiles only

See docs/PHASE_0.md.

License / disclaimer

Public records data remains property of the issuing government body. Contractor Trust Hub provides independent research tooling. Always verify current license status on the official board site before hiring.