Module: <Name> (<kv_module_control key> / <kv_module_registry key>)

Status: <one of the vocabulary below> · Last validated: <YYYY-MM-DD> · Priority: <P0–P3>

Status vocabulary (use the emoji + word): ✅ Fully implemented · 🟢 Production verified · 🟡 Partially implemented · 🟠 Needs validation · 🔴 Not implemented · ⚠️ Legacy · 🔵 Deprecated · ❓ Requires investigation. Definitions in ../../METHODOLOGY.md.

A. Purpose

• What the module does, who uses it, the business objective, the revenue model.

B. Actors

• Which identities touch it (customer, the specific merchant/provider type, staff, admin, partner).

Link each to ../../10-actors/README.md.

C. Entry points

• URLs / routes / nav entries (or "no entry point — hidden", proven by grepping nav registries).
• Both consumer and merchant surfaces. Cite the page files.

D. Onboarding / preconditions

• Module activation (kv_module_control), enrollment (kv_module_registry), membership, KYC.
• Required info/documents, approval path.

E. Feature registry (this module)

Each feature gets a stable ID <PREFIX>-NNN (see ../../STATUS.md for prefixes).

F. Process flows

For each major flow, one section/file: User action → Frontend → Validation → Dispatcher/API → Service/method → DB writes → External svc → Response → Notification → Final state Cite the real files and the real tables at each hop. Include the failure branches, not just success.

G. Data model

• Tables owned by this module: exact name, purpose, PK (usually rowId), key columns, status

columns, the convention-based relationships (this schema has few declared FKs — say so).

• Link the generated dictionary page: ../../90-database/tables/<table>.md.
• Note any table that exists but is empty (0 rows) and whether it is the real store or a

dormant/alternative one — this is a common trap.

H. Financial impact

• Payment methods, wallet debit/credit, commission, GST, invoice, refund, settlement, escrow.
• Tie every money movement to the central ledger: kv_order_finance_master /

kv_order_finance_entries keyed by (module_key, order_table, order_id). See ../../40-financial/central-finance-ledger.md.

I. Business rules

• Each rule as BR-<MODULE>-NNN: description, trigger, condition, action, DB/financial impact,

source path:line.

J. Notifications

• Per event: Trigger → channel(s) (in-app/push/email/SMS/WhatsApp) → recipient → template → table.

K. State machines

• Each stateful entity's lifecycle: states, who/what triggers each transition, allowed &

forbidden transitions, DB column that holds the state, money/notification side effects.

L. Error catalogue (this module)

• Each error <PREFIX>-Exxx: message, technical cause, trigger, impact, detection, resolution,

tables to inspect, logs, severity, status, related errors. Feeds the global Error Center.

M. Cross-module dependencies

• This module → other module: trigger, data exchanged, tables/classes, failure behavior.

N. Change-impact (if you change this…)

• What other modules/tables/APIs/money flows/notifications are affected; what to test.