# House-Ka

**www.house-ka.com** — Homes-for-sale aggregator for Canada **outside Québec**,
Ontario first. A Groupe KA service, sister site of
[Immo-Ka](https://www.immo-ka.com) (Québec).

House-Ka continuously aggregates homes publicly listed by Canadian real-estate
brokerages and teams whose sites run the **RealtyPress** WordPress plugin on
the **CREA DDF** feed. Each site exposes its board's full inventory; a single
generic connector (`immoka/connectors/realtypress.py`) covers them all, and
cross-site duplicates are masked by DDF number (`external_id = ddf<id>`).

## Architecture

Forked from Immo-Ka on 2026-08-27 (the Ontario expansion paused there moved
here). The Python package keeps its historical name `immoka`.

- **Backend** — FastAPI + SQLite (`data/immoka.db`), same pipeline as Immo-Ka:
  connectors → `ingest` → dedup → `quality` (relaxed publication rule: price +
  city; type/description enrich over time via detail passes) → API.
- **Frontend** — React/Vite, **English**, pine/cream/serif skin (deliberately
  different from Immo-Ka's cherry). Routes: `/`, `/property/{uid}[/{slug}]`,
  `/for-sale/{city}[/{type}]`, `/type/{type}`, `/rates`, `/agencies`, `/stats`.
  Map = Ka Maps (`@groupe-ka/ka-maps`, expected at `../../ka-maps`).
- **SEO** — `immoka/seo.py` renders server-side HTML (meta, JSON-LD, sitemaps)
  in English.
- **Mortgage engine** — shared with Immo-Ka (`immoka/mortgage/`), national
  Canadian rates. See `docs/mortgage-engine.md`.
- **Removed vs Immo-Ka** — everything Québec-only: Hydro-Québec estimates,
  BDZI flood, RSQAQ air, gazquebec, rental registry, quartier (census),
  Vrai-Prix, movers/inspectors directories, PDF listing sheets, all QC
  connectors.

## Canonical property types (English)

`House, Condo, Townhouse, Semi-detached, Duplex, Triplex, Multi-family,
Cottage, Mobile home, Land, Farm, Commercial, Parking` —
see `immoka/normalize.py`. DDF list cards carry no type: most listings get
their type when their detail page is fetched (`IMMOKA_RP_DETAIL_LIMIT` per
source per sync).

## Run

```bash
python run.py sync [source ...]   # sync listings
python run.py watch [minutes]     # sync loop (default 60 min)
python run.py serve [port]        # API + frontend (default 8098)
python run.py list                # registered connectors
python run.py geocode [n]         # geocode listings missing coordinates
python run.py mortgage-sync       # collect mortgage rates
```

`.env`: `IMMOKA_BASE_URL=https://www.house-ka.com`,
`IMMOKA_RP_DETAIL_LIMIT=<n>` (detail pages fetched per source per sync).

## Deployment

M4M64b, `~/apps/house-ka`, PM2 (`house-ka-web` :8098, `house-ka-sync`,
`house-ka-ngrok` → www.house-ka.com). Remote-first: the repo on the node is
the source of truth, `origin` = spbgit (`gitsrv:house-ka.git`).

## Adding sources (rest of Canada)

RealtyPress sites exist across Canada. Census & instructions:
`docs/ontario-agencies.md` (method transposes to any province). Add the site
to `data/ontario_agencies.json` + an entry in `data/sources.json`, then
`python run.py sync <id>`. The coordinate guard covers all of Canada.