30-core/search-location-radar.md

Search, Location & Radar (Universal Entry)

Status: 🟢 Production (radar live) / 🟡 Universal Entry live-but-degraded · Last validated: 2026-09-06

How Koovira resolves where you are and what's near you, and the "just ask" Universal Entry layer. Validated against classs/KooviraLocation.php, forms/doaction_radar.php, forms/doaction_ue.php + schema.

Location source of truth

postal_code_master (158,141 rows) is the canonical location dataset for the whole platform. district_name = the CITY level; city_name = the postal locality (unusable as "city"). Index before querying (see memory postal-code-master-canonical-location).

KooviraLocation (classs/KooviraLocation.php, ~1,360 lines) resolves and caches the visitor's location; forms/doaction_radar.php is the AJAX surface.

Radar actions (`forms/doaction_radar.php`, validated)

Location: LOCATION_SET_SESSION, LOCATION_UPDATE, POSTAL_LOOKUP, POSTAL_NEARBY, CITY_SEARCH, CITY_LIST, CITY_SET_SESSION, GOOGLE_CONTACTS_IMPORT. Per-vertical "near me" (each returns nearby supply for that vertical): RADAR_FRIENDS_NEAR, RADAR_PROFESSIONALS_NEAR, RADAR_PEOPLE_NEAR, RADAR_HOTELS_NEAR, RADAR_PLACES_NEAR, RADAR_REALESTATE_NEAR, RADAR_PRODUCTS_NEAR, RADAR_JOBS_NEAR, RADAR_RESTAURANTS_NEAR, RADAR_CLASSIFIEDS_NEAR, RADAR_BUSINESSES_NEAR, RADAR_EMPLOYERS_NEAR, RADAR_EVENTS_NEAR, RADAR_SERVICES_NEAR. Entry pages: /nearmeradar.php, /browse_location.php.

Universal Entry ("Just Ask Koovira")

The homepage "one box" that routes a free-text need to the right vertical. Code: forms/doaction_ue.php, incfiles/_home_search_form.php, tools/ue/.

Table	Rows	Role
`kv_ue_capability_registry`	20	the capabilities the box can route to
`kv_ue_supply`	308,997	precomputed supply snapshot per capability/area
`kv_ue_enquiry`	17	real user enquiries (2026-08-22 → 09-05, corrected 2026-09-06 — was cited as ending 09-02)
`kv_ue_outcome`	0	outcomes credited — none ever

Control: kv_module_control.universal_entry master_status=Yes but frontend_visibility=No (on but dark); kv_module_registry.universal_entry is_active=No. It is live and taking real traffic via the homepage composer (universal.php 301-redirects to index.php).

Validated live defects

Supply job queries a renamed table (serving_listings → entity_listings) and errors → the

308,997-row kv_ue_supply snapshot is frozen/drifting.

UE crons were never installed (supply refresh, outcome reconciliation) → kv_ue_outcome = 0.
Routing misses + login walls on several of the last enquiries.
No admin console — capability tuning requires raw DB writes (0 hits for universal_entry

under padmin/).

Ranking / discovery inputs

Search/radar ranking blends: distance (haversine over postal_code_master geo), listing availability, merchant active/verified state (KYC), membership tier (Gold/Silver/Free ordering + boosts company_business_boost_orders), ratings/trust (KvRatingAggregator, ai_trust_scores), promoted listings. SEO location pages (/{module}-in-{city}, rating-gated /top- pages) route via index.php (see memory seo-location-and-analytics-system).

Business rules

BR-LOC-001 — all location data derives from postal_code_master; district_name is the city level.
BR-SRCH-001 — only active + (where required) KYC-verified + published supply is discoverable.
BR-UE-001 — UE routing needs a kv_ue_capability_registry entry; unmatched intents fall through.

Errors (prefix `SRCH-E` / `UE-E`)

UE-E001 enquiry matched nothing — no capability/synonym; needs a registry row (DB-only today).
UE-E002 supply stale — the supply-refresh job errors on the renamed table.
SRCH-E001 "near me" empty — no supply in radius, or supply not active/verified.

Change-impact

Radar/search feed every module's discovery; UE feeds the homepage. Re-test: location resolution, a couple of RADAR_*_NEAR calls, and (for UE) fix the supply table name + install the two crons.