25-merchant-suite/overview.md

Merchant Business Suite

Status: mixed (see each tool) · Last validated: 2026-09-06

The merchant-facing toolset under merchant/ (355 pages). Nav is merchant/includes/nav_registry.php (mn_primary_groups()) + merchant/page_sidebar/*_pagegroup.php — not mn_module_desks() (data-only; rendering removed 2026-09-03). Each tool below is a candidate for its own full page.

CRM & Leads — 🟢/🟡 Production

Code: merchant/crm.php, merchant/pages/crm_dashboard.php; classs/GlobalLeadManagerModule.php,

classs/LeadUnlockService.php. APIs: api/crm/cases.php, api/crm/tickets.php, api/crm_intake.php (scopes crm.read/crm.write).

Tables: crm_accounts (218, 2026-09-06 — was 210), crm_cases (1,000, 2026-09-06 — was 959),

crm_tickets (176), crm_communications (455), global_lead_manager (42), lead_unlocks (2). crm_lead_scores/crm_module_workflows = 0 (scoring + workflow automation dormant).

Pay-per-lead gap: LeadUnlockService is production-grade (advisory lock, idempotent) but the

fee resolves through empty kv_commission_rules → fee=0.00; both existing unlocks are free. See ../40-financial/commission.md.

Products / Inventory / Orders — 🟢 (see CommerceX)

merchant/ecommerce_products.php, ecommerce_inventory.php, orders.php. Product master = products_master (24,761). Inventory reads products_master.stock_quantity (dedicated seller_inventory/merchant_warehouses = 0). Detail: ../20-modules/ecommerce/.

POS / Billing — 🟡 Partial

Code: merchant/pos_terminal.php, pos_dashboard.php, pos_reports.php.
Tables (anomaly): pos_sale = 0 but pos_register (5), pos_payment (4) have rows — child

rows without sale headers; needs a runtime trace of one checkout. pos_subscription = 0, unpriced.

Website Builder — 🟢 built / 🟡 unsold — P0 revenue

Code: merchant/website_builder_*.php (30 routes, corrected 2026-09-06 — was cited as 31),

merchant/includes/WebsiteBuilderService.php, CanvasBrandKit.php, CanvasImporter.php; merchant/api/website_*.php (28 endpoints, corrected 2026-09-06 — was cited as 30).

Tables: merchant_websites (4), merchant_website_pages (13), merchant_website_templates (346),

merchant_website_subscriptions (0). Plans: hosted ₹3,000/yr, self-hosted ₹25,000/yr — 0 sold.

Hosts the OIDC "Sign in with Koovira" (koovira_sso_clients = 10) — see Developer platform.

Code: merchant/pages/marketing.php, merchant/pages/email_marketing.php, merchant/campaigns.php

(corrected 2026-09-06 — not under pages/; merchant/pages/marketing_campaigns.php also exists); classs/MarketingModule.php, MarketingLineModule.php, KvWhatsAppCloud.php; apiportal/social/ (Social Command Center).

Tables: kv_marketing_line (54: pay-per-use lines — WhatsApp ₹1,000/yr + ₹0.25/msg, Email ₹500/yr
₹0.10/msg; only ~2 active), wa_templates (149), email_queue (1,555 transactional),

email_campaigns (0 — campaign path never used). Social Command Center: 3 subscriptions sold but hidden from merchant nav (reachable only via apiportal/). Correction (2026-09-06): email_queue re-counted at 1,673 (was 1,555 — grows continuously, transactional; not a stale claim, just re-dated).

Developer Platform — 🟡 Partial (single tenant) — see also `/devportal/`

Code: merchant/pages/developer_api.php, classs/DeveloperApiModule.php; public devportal/index.php.
Tables: kv_api_clients (21, all one company_id), kv_api_tokens (27), kv_api_endpoints (18

live), kv_api_scopes (38), kv_api_request_logs (91). OIDC: koovira_sso_clients (10).

Full detail is the external portal — this internal manual covers the engine; devportal/index.php

is the public API catalogue (DB-driven). Gaps: no usage billing, webhooks advertised but not built, "API Documentation" CTA is a dead link.

Billing / Invoicing / Accounting — 🟢/🟡

Tables: kv_billing_invoices (285, 2026-09-06 — was 232), kv_billing_transactions (870,

2026-09-06 — was 738), kv_billing_master (881), kv_billing_credit_notes (18); accounting_journal (2,422, 2026-09-06 — was 2,249; real double-entry via AccountingEngine).

Gap: recurring billing not running (kv_billing_subscriptions = 0). Accounting admin screens exist

but are hidden from padmin nav (not in nav_registry.php).

Correction (2026-09-06, money-validation pass): "real double-entry" needs qualifying — a

confirmed defect in WalletModule::journalAccountsFor() (classs/WalletModule.php:952-983) causes 995 of 2,422 accounting_journal rows (41%, 2026-09-06) to be booked to REVENUE_GENERAL by default, including escrow/refund/transfer wallet movements that are not platform revenue. See ../40-financial/wallet.md for the full finding — the double-entry mechanics are real, but a large share of the account tagging is currently wrong.

Prism (BI / forecasting) — 🟡 Partial

Per-vertical only: merchant/ecommerce_prism.php, food_prism.php, hotels_prism.php (3 of 13).

Forecast falls back to a linear baseline when no model row exists. ai_forecast_models (4), ai_forecast_runs/predictions (0). No top-level "Prism" nav, no paywall.

Cross-cutting notes (validated)

Merchant nav truth = mn_primary_groups() + *_pagegroup.php; ignore mn_module_desks().
Several complete tools are hidden (Social Command Center, Accounting, full OIDC inside Website

Builder) — "built" ≠ "reachable"; verify nav before claiming a merchant can find it.

Most merchant revenue lines are priced but ~0 realised (Website Builder, marketing lines, POS

subscription, developer billing) — the gap is promotion/wiring, not engine.

To expand

Each tool above deserves a full page (feature registry, flow, data-model, errors) — start with CRM (most-used) and Website Builder (P0 revenue).