# UAE new-project analysis — applying the Malaysia structure to Bayut data

> Status: **built as UAE v2 (2026-10-08) — option A of §6.** What shipped, and where it differs
> from this design, is [uae-v2.md](/docs/modules_handbook/shared/project-catalogue/uae-v2.md): the
> listing keys stay `price_rm` / `psf_rm` (holding AED) rather than §4.3's neutral names, the
> off-plan-first rule is the existing post-2016 age rule (GPS-only buildings carry no year), and UAE
> buying costs / service charge print `-` rather than §4.4's model. The rest is the design as written. Part of the project catalogue doc set — the map is
> [start-here.md](/docs/modules_handbook/shared/project-catalogue/start-here.md).

## 1. The goal

The same flow a member gets on a Malaysian new project, for a UAE one:

1. Pick a new project → see **every layout with its price**.
2. **Market value** — is the layout priced above or below the market?
3. **Rental analysis** — ready buildings within **1–2 km**, same bedrooms, their **rent per sqft**.
4. **Calculate** — rent for this layout, gross yield, monthly cashflow.

## 2. How Malaysia does it today (read the code, not just this)

| Step | Malaysia | Where |
|---|---|---|
| Layouts | `catalog_floor_plans` (name, sqft, bedrooms, **price**) from PropertySifu | `CatalogProject::officialFloorPlans()` — falls back to *all* plans when no PropertySifu source exists |
| Evidence | EdgeProp **source rows** within 2 km of the project, each carrying `asking_sale_listings`, `asking_rental_listings`, `psf_median`, `price_median`, `total_transactions` | `CatalogProjectSource::scopeNearbyProviderCoordinates()` (haversine on the source's own lat/lng) |
| Market value | median **asking** PSF of the nearest comparables (1 km ring if ≥ 2, else nearest 10 within 2 km) × layout sqft; verdict ±15 % | `AnalysisEngineService::build()`, `PricingComparables::select()`, `calculateVerdict()` |
| New-project rule | comparables limited to recent developments (completion > 2016) | `filterRecentDevelopments()` |
| Rent | median of listing PSF over the 10 nearest comparables × layout sqft; 1 km then 2 km | `projectInvestment.js` `petaLayoutRent()`; PHP twin `RentalPrediction::forLayout()` |
| Yield / cashflow | rent × 12 / price; rent − instalment − maintenance | `ProjectInvestmentSummary.vue`, `FinancialProjectionService` |
| Precompute | `catalogue:precompute-analysis` → `catalog_floor_plan_analytics`; `layouts:project` → `layout_analyses` | catalogue admin domain only |
| Page | `Main/Site/ProjectDetail` (`ProjectDetailContent.vue`, `ProjectInvestment*.vue`) | `ProjectDetailController::malaysiaPageProps()` |

**What blocks the UAE today:** `config/markets.php` has only an `MY` profile and
`MarketProfile::resolve()` throws for any other country; the engine reads evidence from
`edgeprop` only (`AnalysisEngineService` ~L91, ~L236); currency `RM`, the MYR rent band, the
post-2016 age rule, MY loan/maintenance/stamp-duty defaults are literals in PHP and Vue.

The **current UAE page** (`showUae` → `BuildAeProjectDetail` / `BuildAeProjectAnalysis`,
`ProjectDetailAe.vue`) is a separate verbatim port of peta-new on the paid Estate UAE RapidAPI.
It is community-level: average rent per bedroom, no rent PSF, no radius, no building comps; its
per-layout prices are fetched but not rendered.

## 3. The mapping — Bayut data into the Malaysia structure

| Malaysia piece | UAE source (Bayut, no paid API) | Shape it must arrive in |
|---|---|---|
| Layouts with price (PropertySifu) | The project's **off-plan unit listings** (Algolia `bayut-production-ads-en`, `project.externalID`): beds, size, asking price. Cluster per bedroom by size (±5 %), ≥ 2 listings. Layout price = median asking, `price_from` = lowest. Bayut **floor plans** (`/api/floorPlans/`, types A/B…, 2D/3D images) attach by bedrooms where they exist (~37 % of Dubai projects) | `NormalizedProjectRecord::floorPlans` → `catalog_floor_plans` (sqft, bedrooms, price, units_count) via the existing ingestion; images as `floor_plan` media |
| Evidence rows (EdgeProp) | **Bayut sources for nearby locations**: every ready building (`building:{id}`, 14,959 with GPS) and every new project (`project:{id}`) | `catalog_project_sources.fields` with `latitude`, `longitude`, `asking_sale_listings`, `asking_rental_listings`, `psf_median`, `price_median`, `total_transactions`, `completion_year` |
| `asking_sale_listings` | **DLD sale transactions**, last 12 months, from `POST /api/transactions` (purpose `for-sale`) — better than asking prices: they are registered sales | one row per sale: `price`, `psf`, `sqft`, `bedrooms`, `date`, plus `market` = primary / resale and `status` = off-plan / ready |
| `asking_rental_listings` | **Ejari rent contracts**, last 12 months (purpose `for-rent`) | one row per contract: `price` = **annual ÷ 12** (the engine is monthly), `psf`, `sqft`, `bedrooms`, `date`, `contract` = new / renewal |
| Recent-development rule | Compare a new project against **nearby new projects' sales** (off-plan primary + off-plan resale), not the 10–15-year-old ready stock around it | engine new-project branch reads off-plan rows first |
| Units | Bayut sizes are **sqm** → × 10.7639 at ingest; rent is **annual** → ÷ 12 at ingest | everything downstream stays sqft / monthly, unchanged |

Two UAE-specific outputs fall out of the same data and are worth showing:

- **Value against new-launch market** (off-plan sales nearby) — the like-for-like verdict.
- **Value against ready market** (ready resale nearby) — what the unit is worth if it traded
  like today's completed stock; the gap is the handover risk/premium.

## 4. Engine changes (small, contained, MY output unchanged)

1. **`config/markets.php` → add `AE`**: currency AED / `AED`; `rental_sanity` monthly 1,000–200,000;
   no T20/M40/B40 segments (neutral labels); UAE narratives; a `new_project_comparables` rule
   (`off_plan_first`) replacing the hard-coded post-2016 cut for this market.
2. **`market_provider` per profile** — MY `edgeprop`, AE `bayut`; replace the two hard-coded
   `CODE_EDGEPROP` reads in `AnalysisEngineService` (and `MarketSourceOverlay`,
   `OwnProjectPricing`, `CatalogueDetailService` amenities) with the profile's value.
   `EngineRegressionLockTest` must stay green — MY is byte-identical by contract.
3. **Listing-row keys**: the engine reads `price_rm` / `psf_rm`. Accept provider-neutral
   `price` / `psf` with the old names as fallback, rather than writing AED into an `_rm` key.
4. **Buying costs / financing per market** (Vue `buyingCosts.js`, loan seeds, maintenance):
   UAE = DLD 4 % + registration/admin fees (confirm the current DLD schedule before shipping);
   mortgage defaults 80 % LTV (expat, first home ≤ AED 5M), 25 years, ~4.5 % — but banks lend far
   less on **off-plan** (often ≤ 50 % until handover), so the cashflow must model the payment plan
   until handover and the mortgage after it; **service charge AED per sqft per year** in place of
   RM 0.35 psf/month.

## 5. Data pipeline additions (extend `catalogue:scrape-bayut`)

| Step | Requests (UAE-wide) | Notes |
|---|---|---|
| Off-plan units → layouts | ~120 | partition by community so each query < 1,000 hits (already proven: 116,599 units) |
| Floor plans per project | ~3,000 | `/api/floorPlans/?location_slug_en=…`; images go through `catalogue:store-bayut-media` |
| Comparables per location | ~2 per building/project × bedrooms | recent 12 months, **capped** (e.g. latest 60 sales + 60 rents per location) — multi-location queries are allowed (`locationExternalIDs` + `locationLevels` = slug depth), 20 hits/page |
| Geo-only ready buildings | 1 per 1,000 | create `building:{id}` sources for the ~11,800 buildings that have GPS but no guide |

Then the existing chain runs unchanged: `catalogue:sync bayut --full` →
`catalogue:precompute-analysis --apply` (AE layouts) → `layouts:project --country=AE --run`.

## 6. The page — a decision is needed

| Option | What | Trade-off |
|---|---|---|
| **A. Reuse the Malaysia page for UAE** (recommended) | Route AE projects that have Bayut layouts to `malaysiaPageProps()` behind a config flag; make currency/costs come from the market profile | Members get the exact MY experience (Units & Price, Market Value, Rental by Project (Nearby), Financial Projection, saved Layout Analysis). The current AE page stays as the fallback until switched off |
| B. Extend the current AE page | Add a Bayut-powered "Nearby rental" + per-layout table as new payload keys | Smaller change, but keeps two engines; the AE page's formulas are a verbatim port and must not be edited |

## 7. Prototype results (live Bayut data, 2026-10-08)

Method exactly as §3. `uae/prototype.py` in the session scratchpad; not committed.

| Project · layout | Asking AED/sqft | New-launch market (nearby off-plan sales) | Ready market (nearby resale) | Rent AED/sqft/yr (1 km) | Gross yield |
|---|---|---|---|---|---|
| Binghatti Etherea (JVC) · 1BR 577 sqft · 188 listings | 1,820 | 1,487 → **+22 %** | 1,022 | 87.7 | 4.8 % |
| Binghatti Etherea (JVC) · 2BR 872 sqft · 134 listings | 1,863 | 1,371 → **+36 %** | 1,104 | 99.6 | 5.4 % |
| Sobha Orbis E (Motor City) · 1BR 639 sqft | 1,878 | 1,700 → **+10 %** | 917 | 62.8 | 3.3 % |
| Binghatti Aquarise (Business Bay) · 1BR 790 sqft | 2,420 | 2,351 → **+3 %** | 1,370 | 104.3 | 4.3 % |
| Binghatti Aquarise (Business Bay) · 2BR 1,090 sqft | 2,544 | 2,777 → **−8 %** | 1,526 | 108.8 | 4.3 % |

Within 2 km of each project there were ~120 ready buildings with 12-month rent and sale
records — e.g. 18,422 rent contracts and 2,478 sales within 1.5 km of Binghatti Etherea.

**What the prototype taught:** priced against the *ready* market every new launch reads 30–55 %
"overpriced" — the surrounding stock is a decade older. Malaysia hit the same problem and solved
it with the recent-development rule; for the UAE the equivalent is §3's off-plan-sales benchmark.

## 8. Phasing

1. **Data** — layouts from units (+ floor-plan images), comparables per location, geo-only
   building sources. Tests: normalizer clustering + one ingest round-trip.
2. **Engine** — AE profile, provider from profile, neutral listing keys, off-plan-first rule.
   Tests: `EngineRegressionLockTest` unchanged (MY), one AE engine test on a fixture.
3. **Page** — option A or B (§6), currency/costs from profile.
4. **Precompute + publish** on the Hub; compare a sample against the prototype numbers.

## 9. Open questions

- §6: reuse the Malaysia page (A) or extend the AE page (B)?
- Layout price: median asking of listings (prototype) or the lowest ("from")? Listings mix
  developer stock and investor resales (titles: ~11k say resale, ~3.7k say developer).
- Coverage outside Dubai: Bayut's transaction ledger is DLD (Dubai). Abu Dhabi / Sharjah / RAK
  projects would get layouts and listing-based asking comps only.
- Bayut's terms of use restrict automated collection — a business decision before running at scale.
