- HTML 98%
- Python 2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| data | ||
| docker | ||
| hunter | ||
| reports | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| config.toml | ||
| Dockerfile | ||
| house_hunter.py | ||
| README.md | ||
NRCC & NJ Multi-Region House Hunter
Automated market monitor and interactive housing portal for residential real estate across:
- NRCC / Washington, D.C. Metro (
dmv): Montgomery County, MD, Anne Arundel County, MD, Howard County, MD, Prince George's County, MD, Fairfax County, VA, Loudoun County, VA, Prince William County, VA, Arlington County, VA, and Alexandria, VA (commuting to NRCC Headquarters at320 First St SE, Washington, DCon Capitol Hill via WMATA Metro, MARC, and VRE). - New Jersey (
nj): Morris County, Hunterdon County, and Somerset County, NJ (commuting to NYC via NJ Transit).
Runs twice daily (8:00 AM and 6:00 PM Eastern) as an automated Forgejo Action or scheduled monitor. It pulls active listings (house, townhouse, condo) from Redfin, models affordability against a $180,000 pre-tax income profile (24% conservative DTI = $3,600/mo, 28% standard front-end rule = $4,200/mo), resolves county and municipal effective property tax rates across VA, MD, DC, and NJ, evaluates pet & yard space suitability (dog + cat), neighborhood safety & lifestyle, and commute time to NRCC / NYC, and publishes interactive Map (map.html) and Tabular (latest.html, latest.md) dashboards.
What It Does
- Fetches Active Listings: Queries Redfin for active houses, townhouses, and condos ($200k–$550k) across Morris, Hunterdon, and Somerset counties.
- True Monthly Cost Calculation:
- Uses your available cash ($60k) minus closing costs (3%) towards down payment.
- Calculates monthly P&I at 30-year fixed rate (7.40% baseline).
- Looks up the official 2025 NJ Division of Taxation effective property tax rate for each specific municipality.
- Adds property-specific HOA fees, homeowners insurance, and tiered PMI.
- Filters out any home where total monthly outlay exceeds $3,600/month.
- Smart Scoring & Ranking:
- Living Space (Square Footage) — 35% weight
- Outdoor Land (Lot Size) — 25% weight
- Central Air conditioning — 20% weight
- Priority Towns (Somerville, Raritan, Morristown, Morris Plains, Clinton, High Bridge) — 10% weight
- Walkability (Walk Score) — 10% weight
- Hybrid Auto-Enrichment:
- Cross-references top candidate matches via Redfin property details (above/below the fold) for central A/C and sq ft.
- Falls back to official NJ MOD-IV Property Tax Assessment Records for building square footage.
- Reports & Git Persistence:
- Generates
reports/latest.mdand dated snapshots (reports/YYYY/MM/...). - Runs automatically on your Forgejo
nasrunner and commits updates directly.
- Generates
Configuration
Edit config.toml to adjust parameters:
search.min_price,search.max_price: Price window.search.property_types:["house", "townhouse", "condo"].budget.max_monthly_total: Maximum monthly budget (default$3,600).budget.cash_available: Total cash for down payment and closing costs (default$60,000).budget.interest_rate_pct: Your quoted mortgage interest rate.scoring: Weights for walkability, sqft, and central air.
CLI Usage
Run manually from the project root:
# Run full pipeline (fetch, filter, enrich walk score, render report)
python3 house_hunter.py run
# Run pipeline and push report to git
python3 house_hunter.py run --publish
# View listings needing manual research (central air or missing sqft)
python3 house_hunter.py research
# Auto-cross-reference property details (sqft & central A/C) for top matches
python3 house_hunter.py enrich-details --top 25
# Record researched info for a listing manually
python3 house_hunter.py enrich <KEY> --central-air yes --sqft 1800 --source "Zillow/tax record"
# Re-render reports with current enrichment data
python3 house_hunter.py render
# Commit and push current reports
python3 house_hunter.py publish
Testing
Run unit tests:
python3 -m unittest discover -s tests -v
24/7 Web View & Docker Deployment (Unraid)
The project includes an ultra-lightweight Nginx container that serves the Interactive Visual Map Dashboard (/), the Tabular Report (/report), and the Raw Data API (/data/listings.json).
Running via Docker on Unraid
The image is automatically built and pushed to your Forgejo Package Registry by the .forgejo/workflows/docker-publish.yml action:
docker run -d \
--name house-hunters-web \
--restart unless-stopped \
-p 8085:80 \
git.rcslabs.dev/john4064/house-hunters:latest
Once running, access the dashboard at http://<nas-ip>:8085.
Remote Repository Setup (Forgejo)
To connect this local repository to your Forgejo instance for automatic pushes:
cd ~/.gemini/antigravity/scratch/house-hunter
# 1. Add your Forgejo remote URL
git remote add origin https://<your-forgejo-host>/<username>/<repo>.git
# 2. Configure git credential helper so unattended pushes succeed without password prompts
git config credential.helper store
# 3. Perform the first push (enter your username and access token once)
git push -u origin main