Table of Contents
Introduction
Find A Crib maps every rent-stabilized building in New York City, plus rent-controlled and income-restricted housing in San Francisco, Los Angeles, Washington DC and more, and alerts renters the moment a housing lottery or affordable re-rental opens up.
Available on the web at findacrib.com and for iPhone and iPad.
Features
A few of the things you can do with Find A Crib:
- Map of covered buildings. Every NYC building on the DHCR rent-stabilization
rolls, with its HPD owner / managing agent, open violations and complaints.
SF, LA and DC run on the same front end from each city's own records.
- Lotteries and re-rentals. NYC Housing Connect and HCR lotteries, plus
marketing-agent re-rentals that go first come, first served.
- Alerts. Email and iPhone push when a lottery, re-rental or saved
building matches what you're looking for. Alerts can be filtered by
borough, household size and income.
- AI that shows its sources. A nightly reader turns each listing's flyer
into a unit table (rent, household size, income limits). Every number it
extracts must appear in the source text, or that row is dropped
(
claude_features.ungrounded).
- "Do I qualify?" Checks household size and income against each listing's
limits.
Feedback
Feel free to file an issue. Feature requests are always welcome. If you wish to contribute, please take a quick look at the guidelines!
Build Process
You need Python 3.14 (what CI runs) and no API keys.
git clone https://github.com/divinedavis/Find-A-Crib.git
cd Find-A-Crib
python3.14 -m venv .venv && . .venv/bin/activate
pip install requests numpy pillow opencv-python-headless shapely PyJWT segno anthropic cryptography playwright==1.62.0
python3 tests/run_unit.py # unit tests (same as CI)
To look at a front-end change, open the live site with your local files
swapped in. Pages, scripts and styles come from your checkout; the data,
config.js and the API come from findacrib.com, so no keys or data build:
playwright install chromium webkit
python3 scripts/preview.py # desktop window; Enter reloads after you save
python3 scripts/preview.py --device phone # iPhone (WebKit); also --device ipad, --path /sf/
python3 scripts/preview.py --shots shots/after # phone + desktop + iPad screenshots
To test a front-end change, run the user-journey suite. It loads your local
web/index.html over the live site's data in phone, desktop and iPad browsers:
JOURNEYS_SKIP=account_delete,plus_gates,renter_tools,ai_features python3 tests/journeys.py
Large data files (buildings.slim.json and friends) are generated and
gitignored. The journey suite fetches them from findacrib.com, so you don't
need to build them.
Working in a worktree
The owner's checkout uses sibling worktrees (../dhcr-map-<task>) so several
branches can be open at once. A fresh worktree has only tracked files; the
ignored data the app, the builders and the iOS tests need stays in the main
checkout. Create one with:
scripts/new_worktree.sh <task> # branch + ../dhcr-map-<task> + data
It first re-downloads any public data file (the slim and detail building files,
featured.json, the iOS seed) that is over a week old in the main checkout
from findacrib.com, then clones the data with cp -c: on APFS the copy is
instant and costs no extra disk until one side is modified. Build output lives
in each worktree's ios/build.nosync; scripts/clean_builds.sh reports what
it would reclaim (dry run by default, --yes to empty the idle trees,
--keep daily to leave one alone; it never removes ship-history.jsonl).
How the Code Is Laid Out
| Area | Where |
|---|
| Website: everything served at findacrib.com, laid out like the docroot | web/ (web/index.html is the one-file Leaflet app, no build step; web/static/, icons, web/brand/) |
| City pages + their data | web/sf/, web/la/, web/dc/, web/westchester/ (pages generated by pipeline/build_city_pages.py) |
| Data builders, scrapers, alerts, reports (one script per job) | pipeline/ |
| Committed data (DHCR PDFs, boundaries, snapshots of the published feeds, curated inputs) | data/ |
| API (Flask) | api/ (server + auth); shared modules in pipeline/; deploy/api/ |
| Alerts | pipeline/lottery_alerts.py, pipeline/saved_alerts.py, pipeline/apns.py |
| AI features | pipeline/flyer_reader.py, pipeline/nl_search.py, pipeline/claude_features.py, pipeline/ai_gateway.py |
| Database (Supabase / Postgres) | db/ migrations, supabase/functions/ |
| iOS app (SwiftUI) | ios/ (see ios/README.md) |
| Growth engine (SEO pages, outreach) | growth/, pipeline/growth_daily.py |
| Deploy + cron jobs | deploy/, scripts/deploy_*.sh |
| Production layout and nginx snapshot | deploy/README.md, deploy/nginx/ |
| Tests | tests/ |
| Docs, research write-ups, backlog | docs/ |
| Signage and ad creative | marketing/ |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
