# Autonomous Deal-Sourcing & Acquisition Engine — Build Spec

> **Status:** Reference specification / handoff document.
> **Audience:** Technically ambitious investors and developers who want to extend the portal into an automated property deal-sourcing, modelling, and acquisition pipeline.
> **Scope:** This is a *what to build and why* document, not a step-by-step tutorial. It captures the architecture, the data joins that matter, the legal/quality shortfalls that will shape the design, and a suggested MVP sequence.

---

## 1. What this builds

An engine that:

1. **Sources** on-market and off-market property opportunities in a target area.
2. **Enriches** each property with size, comps, tenure, EPC, planning, flood and ownership data.
3. **Models** each property (yield, BRRR, refurb, GDV, tax position) to produce a ranked **deal score**.
4. **Surfaces** deals matching a defined buy-box, with a human-in-the-loop at the outreach/offer stage.
5. **Tracks** everything through a CRM pipeline from sourced → completion.

**The moat is not the scraper.** Anyone can rent an Apify actor. The defensible edge is (a) the appraisal/deal-scoring engine and (b) off-market signal aggregation that portals don't have. Build those first; treat portal scraping as a commodity input the product can survive losing.

---

## 2. Architecture — five layers

### Layer 1 — Ingestion (sourcing)

**On-market**
- Apify actors for Rightmove / Zoopla / OnTheMarket. **Fragile** — portals change their DOM and actively fight scraping. Isolate this so breakage is contained.
- Auction feeds: EIG, Auction House, iamsold. Unsold lots = motivated vendors.
- Estate agent sites directly.

**Off-market (the real edge — all open/licensed, none fragile)**
- **Land Registry Price Paid** — sold prices.
- **Land Registry INSPIRE polygons** — open spatial boundaries.
- **Companies House** — find corporate/portfolio owners.
- **EPC register** (open bulk dataset) — tired stock, floor areas, absence-of-EPC as a long-hold signal.
- **Planning application data** — active landowners = motivated.
- **HMO licensing registers.**
- Probate / absentee-owner signals — **high sensitivity, see §4.**

Normalise everything into a canonical `property` schema **at ingest**: postcode, UPRN, tenure, price, source, timestamp.

### Layer 2 — Enrichment & matching
- Geocode to **UPRN** so the same property from multiple sources deduplicates to one record.
- Attach: EPC rating + floor area, flood risk (EA API), sold comps (Land Registry radius), rental comps (weakest open dataset — see §4), planning history, ownership.

### Layer 3 — Modelling (the appraisal engine — start here)
Per property, auto-run:
- Gross & net **yield**
- **BRRR** viability (money-left-in, ROI post-refinance)
- **Refurb cost** estimate (£/m² banded by condition — flag confidence, don't imply precision)
- **GDV** for development plays (land + build + finance + fees → profit on cost/GDV, residual land value)
- **Tax position:** Section 24, Ltd Co vs personal, SDLT with 5% surcharge, CGT on disposal

Output a **deal score** and rank. This is the product's brain.

### Layer 4 — Outreach (human-in-the-loop)
- Generate offer/enquiry drafts + suggested offer price with comp justification.
- **Do NOT fully automate the send.** Agents blacklist AI-blasted offers, and relationships are the actual edge. Human approves each send. This is also the safer legal posture (§4).

### Layer 5 — CRM & tracking
- Pipeline stages: sourced → appraised → contacted → viewing → offer → legal → completion.
- Comms log, document store, task automation, buy-box alerting.

---

## 3. The £/m² baseline heuristic (worked pilot: Southend-on-Sea)

A concrete, testable entry point: **establish a local £/m² baseline; flag any listing ≥20% below its segment baseline; run flagged properties through the full model.**

### Baseline definition (this is the crux)
A single town-wide average is useless — Thorpe Bay, Westcliff, Prittlewell and Shoeburyness are different submarkets. Baseline must be **local and segmented**:

```
baseline = median £/m² for { postcode_sector × property_type × recency_window }
```

- **Postcode sector** (e.g. SS1 2) — meaningful sample, real submarket.
- **Property type** — flats have structurally higher £/m² than houses; never mix.
- **Median, not mean** — property data is outlier-skewed.
- **Recency window** — restrict to last ~24–36 months or index-adjust older sales.

### The critical data join
```
Sold £/m²  =  Land Registry Price Paid  ×  EPC total-floor-area   (joined on address/UPRN)
Listing £/m² =  live listing price  ÷  floor area (listing sqft preferred, else EPC)
Flag when: listing £/m² ≤ (segment baseline × 0.80)
```

The **Land Registry ↔ EPC join on UPRN** is the single most important and most fiddly step. Addresses are formatted inconsistently; not every sold property has an EPC. This is where data quality lives or dies — budget real effort here.

### Guardrails on the flag
A 20% "discount" is usually an *explanation*, not a deal. Before flagging, filter/classify for:
- **Leasehold short lease / high service charge** — biggest false-positive source. Pull tenure (Land Registry) and lease length (title data) early.
- Poor condition / full refurb (a valid BRRR deal — but the model must *know* it's factoring refurb).
- Ex-LA, non-standard construction, cladding/EWS1, flood zone (relevant for Southend's estuary pockets).
- Stale/incorrect EPC floor area.

The flag means "priced abnormally — find out why", and the model's job is to **classify the reason**: "cheap because refurb" = deal; "cheap because 60-year lease" = trap.

### Statistical hygiene
- **Minimum sample threshold** (e.g. ≥15 comps per segment); fall back to wider geography (sector → district → town) when thin, and record lower confidence.
- Weight recent transactions; index-adjust or exclude stale sales.
- Prefer listing sqft over EPC area where both exist; flag disagreement (possible extension since EPC).

---

## 4. Shortfalls — read before building

### Legal / compliance
- **Scraping Rightmove/Zoopla breaches their T&Cs** and they litigate. Apify shifts the technical burden, not the legal one — *you* use the data. Design so the valuable core does **not depend** on portal scraping.
- **Dataset licensing:** INSPIRE polygons are open; some OS products and bulk title data need a commercial licence. Land Registry Price Paid, EPC, Companies House, planning data are open/licensed and safe.
- **PECR / UK GDPR on outreach:** B2B approaches to agents are lighter-touch. Approaching *individual owners* identified via Land Registry/probate is direct marketing against personal data — you need a lawful basis. Probate/absentee targeting is ethically and legally sensitive; design it in, don't bolt it on. (Three-message-class discipline — service / feedback / marketing, marketing off by default — applies here.)
- **Estate agency / financial promotion rules:** acquiring for *yourself* is fine. A SaaS that advises third parties on investment merit or arranges deals for others can stray into regulated territory — take advice before that pivot.

### The autonomous-offer problem
Agents recognise and ignore/blacklist bot offers, eroding the exact trust that earns the off-market call first. **Keep a human at the offer stage.** Automate sourcing, modelling, drafting, CRM logging — human approves the send.

### Data quality
- **Rental comps are the weakest UK open dataset** — no Land Registry equivalent for rents. Your yield model is only as good as your rent data; this quietly breaks these builds.
- **Refurb cost from photos/text is hard** — banded estimates are wrong often enough to matter. Show confidence, not false precision.
- **Dedupe without UPRN is deceptively hard** — same house, three address formats.
- **EPC floor area is as-measured at assessment date** — misses later extensions/conversions; RdSAP basis differs from RICS/agent measurements; each property can have multiple certificates (dedupe to latest `lodgement-date`).

### Operational / economic
- Scrapers are maintenance-heavy — actors break when portals change.
- Winning deals go fast — a daily batch may surface them after they're gone. Speed of ingest → alert → human action matters.

---

## 5. Expansions (once the core works)

- **Per-investor buy-box matching** — user defines area/yield floor/strategy/budget; engine only surfaces and models fitting deals.
- **Alerting** — "new deal matching your box scored 87 this morning" — the retention hook.
- **Predictive motivated-seller scoring** — combine signals (long time on market, multiple reductions, probate, expired lettings, EPC F/G, absentee corporate owner) into a likelihood-to-sell score. Genuinely valuable IP.
- **Comps-driven offer suggestion** — recommend offer price with justification, not just the find.
- **Auction intelligence** — track lots vs your model; follow up unsold lots.
- **Portfolio/landlord targeting** — Companies House + Land Registry to find multi-property tired-stock owners for off-market portfolio approaches.

---

## 6. Suggested MVP sequence

Prove the **modelling edge**, not the automation, first.

1. **Ingest the safe, high-value open datasets first** — Land Registry, EPC, Companies House, planning. Add portal scraping cautiously and later.
2. **Canonical property store keyed on UPRN** — Postgres + PostGIS (Supabase already provides PostGIS).
3. **Appraisal engine** — the comparative advantage and the defensible core. Start here.
4. **Ranked dashboard + buy-box filter.**
5. **CRM pipeline with human-approved outreach drafting.**

Then layer: enrichment APIs, motivated-seller scoring, alerting, auction feeds, multi-user buy-boxes.

**Validate by eye:** for the first month, manually check flagged properties and confirm the model's "reason classification" against reality before trusting the score. A bounded, familiar pilot market (e.g. Southend-on-Sea) makes this tractable.

---

## 7. Suggested stack

| Concern | Choice | Note |
|---|---|---|
| Store + spatial | Supabase (Postgres + **PostGIS**) | UPRN-keyed joins & dedupe |
| Frontend | Next.js (Netlify/Vercel) | Matches existing portal |
| Ingestion | Apify | Isolated so breakage is contained |
| Job queue / enrichment | n8n or Inngest | Batch enrichment & baseline builds |
| Modelling narrative + drafting | Claude (Anthropic API) | Deal reasoning, outreach drafts |
| CRM | Own tables or existing CRM via API | Pipeline + comms log |

---

## 8. Key data sources reference

| Source | Gives you | Licence status |
|---|---|---|
| Land Registry Price Paid | Sold prices, tenure | Open |
| Land Registry INSPIRE polygons | Spatial boundaries | Open |
| EPC register (bulk) | Floor area (`total-floor-area`, m²), rating, age/type | Open (API key + licence) |
| Companies House | Corporate/portfolio ownership | Open API |
| Planning application data | Active landowners | Open (varies by LPA) |
| Environment Agency | Flood risk | Open API |
| HMO licensing registers | Licensed HMO stock | Open (per council) |
| OS / bulk title data | UPRN, boundaries, owner identity | **Some commercial licence required** |
| Rightmove / Zoopla / OTM | Live listings | **Scraping breaches T&Cs — legal exposure** |

---

*This document is a technical scoping reference. It is not legal advice. Anyone building the outreach, ownership-data or third-party-advisory components should take professional legal advice on UK GDPR/PECR, dataset licensing, and estate-agency/financial-promotion regulation before going live.*