Rebuilding the data
The customer-facing application does not contain or run the national Python pipeline. National data is built by
the independent LookAlike-data-pipeline repository and published as an immutable release.
Repository boundary
Section titled “Repository boundary”The application repository owns the React interface, browser scoring, Cloudflare Worker, authentication, and product APIs. The data-pipeline repository owns source retrieval, feature engineering, curated-brand validation, PMTiles generation, release validation, and R2 publication.
The application repository does not commit national data. For local development, pnpm data:dev copies a
pipeline release or downloads a published one into web/public/data, which Git ignores. The browser-model
contract test uses a small fixture, web/src/lib/fixtures/presence-contract.json, exported by the pipeline’s
export_contract_fixture.py. Re-export it whenever the model math changes.
Build a release
Section titled “Build a release”From the pipeline repository:
python3.13 -m venv .venv.venv/bin/pip install -r pipeline/requirements.txtLOOKALIKE_RELEASE_ID=2026-10-05-01 .venv/bin/python pipeline/run_all.pyThe pipeline writes only inside its own repository:
dist/releases/2026-10-05-01/Raw downloads and intermediate Parquet files remain cached under that repository’s data/ directory.
Publish and activate
Section titled “Publish and activate”Publishing and activation are separate operations:
./scripts/publish-release.sh --remote 2026-10-05-01./scripts/activate-release.sh --remote 2026-10-05-01Publishing uploads objects under releases/2026-10-05-01/. Activation changes the small current.json pointer.
If a release fails validation or upload verification, do not activate it; the application continues using the
previous release.
Refresh cadence
Section titled “Refresh cadence”- Refresh curated brand footprints weekly from All The Places (CC0 weekly scrapes), with OpenStreetMap as the fallback source.
- Adopt new Overture retail-context releases monthly or deliberately.
- Update ACS, TIGER, and metropolitan definitions when their official annual releases are adopted.
A weekly brand refresh should reuse cached national features and geometry. It does not need to redownload or recompute every source.
Consistency guarantee
Section titled “Consistency guarantee”The application test suite reads the packaged release binaries and the fitted presence model, and verifies that the browser TypeScript scorer reproduces the pipeline’s fit values for every curated brand. A scoring change is incomplete until the pipeline output and application consistency test agree.
The product remains a descriptive neighborhood-fit tool. A new data release does not convert its results into revenue, sales, or store-success predictions.