Module: Business Directory & Marketplace (business_directory / —)
Status: 🟡 Partially implemented (3M listings; claim conversion = 0.00%) · Last validated: 2026-09-06 · Priority: P0
The scraped/imported business directory + city marketplace discovery, and the merchant claim funnel that converts a scraped listing into an owned profile. Validated against classs/BusinessListingsModule.php, classs/ClaimKycModule.php + schema.
A. Purpose
Discovery of ~3M businesses (SEO + city marketplace), with a claim → verify → own path that is the top-of-funnel for merchant acquisition. Revenue: verified badge, boosts (buyBoost), and downstream module memberships once claimed.
B. Actors
Anonymous searcher; a business owner claiming their listing; admin (claim approval).
C. Entry points
/businesses.php, /directory.php, /marketplace.php?city=. Claim via ClaimKycModule (claim_otp.php).
Reachability caveat — UPDATED 2026-09-06:directory.phpandmarketplace.phpare still not in any nav registry (greppedincfiles/nav/_nav_map.php— zero hits formarketplace.php;directory.phpappears only in a comment, "nothing links to"), reachable mainly via Universal Entry routing and SEO. Butbusinesses.phpis now nav-linked ("Browse Directory") and a brand-new page,/business_directory_intro.php("Claim Your Business"), was added to the main nav on 2026-09-05 — seeincfiles/nav/_nav_map.php:302-313and the page's own header comment atbusiness_directory_intro.php:1-36. This directly changes the headline gap below — read that section's correction before citing "no CTA" from this doc's own earlier text.
E. Feature registry (prefix DIR-)
| ID | Feature | Actor | Method | Tables | Status |
|---|---|---|---|---|---|
| DIR-001 | Search businesses | anon | searchBusinesses :993 | entity_listings | 🟢 |
| DIR-002 | Business profile view | anon | getBusinessProfile :797 | company_business_profiles, entity_listings | 🟢 |
| DIR-003 | Save business profile | owner | saveBusinessProfile :534 | company_business_profiles | 🟢 |
| DIR-004 | Module listings for a company | owner | companyModuleListings :930 | module tables | 🟢 |
| DIR-005 | Claim a listing | owner | ClaimKycModule::submitListingClaim :685 | claim_kyc_requests, entity_listing_claims | 🟡 (0 claims) |
| DIR-006 | Buy boost (paid promotion) | owner | buyBoost :1366 | company_business_boost_orders | 🟡 |
G. Data model (2026-09-06)
| Table | Rows | Role |
|---|---|---|
entity_listings | 3,025,389 | scraped/imported business listings (the directory) |
entity_listing_claims | 0 | claims ever recorded |
company_business_profiles | 98 (corrected 2026-09-06: doc previously said 63; live COUNT(*) today is 98 — see also ../business-profiles/overview.md BIZ-003, same table) | owned business profiles |
H. The headline gap (corrected 2026-09-06 — the promotion gap is now closed, conversion isn't)
Claim conversion is still = 0.00% (entity_listing_claims = 0, live count today). 3.02M listings, 0 ever claimed, despite a fully-built claim funnel (OTP gate, KYC document upload — 6 claim_kyc_documents rows exist).
(correction: this doc previously said the gap was "entirely promotion-side: no landing page, no intro config, no claim CTA" — that is no longer true as of yesterday. business_directory_intro.php (added 2026-09-05, public, $kvRequireLogin = false) is now a full intro-config landing page ("Claim Your Business") wired into the main nav [incfiles/nav/_nav_map.php:311], built on the same shared intro renderer as careerlab_intro.php/services_intro.php. The landing page itself documents why it was added: a prior audit found entity_listings at 3,024,465 rows and entity_listing_claims at zero, traced the cause to "no landing page, no intro-registry entry, no nav path", and this file fixes exactly that. So the CTA now exists and is nav-reachable — the remaining 0.00% is either (a) too recent to have converted yet (shipped 2026-09-05, one day before this count), or (b) a funnel/awareness problem downstream of the CTA (e.g. traffic, positioning, conversion on the intro page itself) rather than the CTA's mere existence. Re-check the claim count in a few weeks before re-asserting "no CTA" as the root cause.)
See ../../30-core/kyc-trust.md for the claim engine.
K. State machine (claim)
unclaimed → submitted (OTP + docs) → under_review → approved (owned) / rejected / more_info → appealed → resubmitted (loop back to under_review) or withdrawn. (corrected 2026-09-06: doc previously named the states claim_submitted and appeal; the real, validated state list is ['submitted', 'under_review', 'more_info', 'approved', 'rejected', 'appealed', 'resubmitted', 'withdrawn'] per ClaimKycModule.php:547, with 'unclaimed' as the pre-claim listing state [:589, :735].) On approval the listing links to a company_business_profiles row and unlocks module enrollment.
L / M / N
Errors: DIR-E001 claim still not converting (0 claims) — the promotion CTA now exists (business_directory_intro.php, nav-linked 2026-09-05), so this is no longer a "no CTA" gap; treat it as Requires Verification (funnel/traffic) until claims start appearing. DIR-E002 marketplace.php/directory.php (still) unreachable from nav — businesses.php and business_directory_intro.php are the nav-reachable pair now. Depends on KYC, membership, boosts (wallet), Universal Entry (routes here). Change-impact: the claim CTA + landing page shipped 2026-09-05 — re-test the claim funnel end-to-end (it works; it's now surfaced) and re-check entity_listing_claims/claim_kyc_requests counts in the next audit pass to see whether the CTA actually moved conversion.