Module: RealtyVerse / Real Estate (real_estate / realestate+builder)

Status: 🟡 Partially implemented (huge inventory; role data missing → builder/agent roles unreachable; ₹1.9M commission stuck pending — corrected 2026-09-06, was ₹1.3M) · Last validated: 2026-09-06 · Priority: P0

Property listings, projects, agents, builders, enquiries. One module, role picker (Owner/Agent/Builder/Both). Validated against classs/RealEstateModule.php + schema.

A. Purpose

Customers search property + send enquiries; owners/agents/builders list property and projects. Revenue = membership (Builder ₹45k, Agent ₹55k, Both ₹85k/yr) + 5% commission. Realised ≈ 0 (see gaps).

B. Actors

Buyer/enquirer; property owner; agent (property_agent); builder (property_builder); Both (property_builder_agent); admin. Enrollment via realestate + builder keys.

C. Entry points

Consumer: /searchproperty.php, /realestate.php, listing detail, /agent.php?id=, /propertynewlaunched.php. Merchant: realestate dashboard + 12 routes; listing wizard.

Correction (2026-09-06): "+16 routes" was stale. merchant/page_sidebar/realestate_pagegroup.php lists exactly 13 nav entries total (Overview/dashboard + 12: Add Listing, Listings, Projects, Units, Enquiries, CRM Board, Site Visits, Agents, Media, Import/Export, Reports, Permissions) — i.e. dashboard + 12 routes, matching the "13 built screens" figure already used in section H below.

D. Onboarding

Role picker at merchant/setupmodule_details.php:513-527 (Owner/Builder/Agent/Both). createBuilder (:2195), createAgentCompany (:2274), then createListing (:2424) via a multi-step wizard (getOrCreateWizardState :3288, saveWizardStep :3393, sendWizardOTP :3501).

E. Feature registry (prefix RLTY-)

G. Data model (2026-09-06)

H. Financial impact — two validated gaps

1. Role gate blocks the paid SKUs. company_business_profiles has zero realestate rows, so

merchant/includes/init.php:387-395 leaves $activeModuleUserType empty and the Builder/Agent dashboards render "available for Builder accounts" for every merchant. The ₹45k–₹85k/yr plans are unsellable until the role data is backfilled. The "Both" SKU has no writer at all.

1. ₹1.9M commission stuck pending (historical backlog, not a live bug).

commission_transactions where order_table='property_listings': 20 rows, all status='pending', summing ₹19,00,000 (verified live, 2026-09-06 — corrects the previous "14 rows, ₹1.3M"). All 20 rows date to 2026-09-04 (RealEstateModule::closeDeal, classs/RealEstateModule.php:4449). The code's own comment at RealEstateModule.php:4435-4447 states this was fixed 2026-09-05: closeDeal() now inserts status='processed' at RealEstateModule.php:4489 immediately on deal close (no pending→processed pipeline exists anywhere in the codebase, so a row written 'pending' would never move). Net effect: these 20 rows are a pre-fix backlog that will stay pending forever unless backfilled by a one-off migration; any new deal closed today writes processed immediately. No deal has closed since the fix (2026-09-06), so live data cannot yet confirm the new behavior end-to-end — flagged as Requires Verification until the next real closeDeal() call is observed. See ../../40-financial/commission.md.

1. Commission rate mismatch (possible bug, not fixed here). platform_commission_settings has

a realestate_deal row at 5.00% ("founder rate, flat 5%", created 2026-09-04 19:07:11), but RealEstateModule::closeDeal() (:4465) computes commission from $data['commission_percent'] ?? 2.0 — a hardcoded 2.0% default, with no read of platform_commission_settings at all. All 20 live rows were charged at 2.00%, not 5.00%. This looks like a genuine discrepancy between the configured founder rate and what the code actually charges; not corrected here per task scope — flagging for engineering follow-up.

Lead storage is split three ways (property_enquiries / crm_cases / global_lead_manager) — which is canonical is a product decision; the agent performance screen reads the empty global_lead_manager, so it renders empty. Flag, don't guess.

K. State machine (property_listing)

draft → pending → approved → published → suspended → archived (admin via adminSetListingActive). Enquiry: new → contacted → qualified → closed.

L. Errors (prefix RLTY-E)

• RLTY-E001 "available for Builder accounts" for everyone — root cause: no realestate row in

company_business_profiles (role gate). Backfill role data.

• RLTY-E002 agent performance screen empty — reads global_lead_manager (0 rows) not

property_enquiries.

• RLTY-E003 pre-2026-09-05 commission rows stuck pending (20 rows, ₹19,00,000, see H.2) — the

underlying settlement-status bug was fixed 2026-09-05 for new deals, but the historical rows have no backfill path.

M / N. Dependencies & change-impact

Membership (role SKUs), KYC, wallet, commission, CRM/leads, geo. Fixing the role gate unlocks 13 built screens + the plan family — re-test builder/agent dashboards after backfilling company_business_profiles.