Platform Architecture Overview
Validated against code + live DB on 2026-09-06.
Koovira is a modular local-commerce + social super-platform for India: one account and one wallet across ~20 verticals (commerce, food, hotels, rides, real estate, jobs, services, classifieds, events, social, dating, and more), plus cross-cutting engines (trust, credit score, endorsements, negotiation, comparison, universal-entry/radar) and a merchant business suite (CRM, POS, marketing, website builder, developer APIs).
This page is the map. Each subsystem links to its detailed page.
Technical architecture (validated)
- Stack: PHP 8.3 on nginx (prod) / Laragon (local); MariaDB 10.11 (
koovira_newmasterdb_opt,
1,797 tables); Redis 7. No CDN by house rule — assets are served locally/bundled.
- Not a framework app. There is no Laravel/Symfony router or ORM. It is a large PHP codebase
organized by convention:
- Front-end pages = root
*.php(733 files) — e.g.mycart.php,ecomproductlist.php.
Each includes config/common_includes.php and renders server-side.
- Business logic =
classs/(461 class files) — e.g.CommerceOrdersModule.php,
WalletModule.php, CommissionEngineModule.php. These hold the real logic and DB writes.
- Write dispatch =
forms/doaction_*.php— most state-changing actions POST to a
doaction_<area>.php dispatcher which validates and calls a classs/ module.
- JSON/AJAX APIs =
api/(internal, session-based) andapi/developer/+api/v1/
(external, token-based via the developer platform / OIDC).
- Admin =
padmin/(super-admin back office); Merchant =merchant/(business suite). - Background =
cron/scripts (see the Cron/Background section — to be documented). - DB access = a single guarded
$conn(KVGuardedPDO) everywhere; DDL is blocked on the web
tier. Details: bootstrap-and-config.md.
- Identity of a row =
rowId(notid) on most tables; relationships are convention-based
(few declared FK constraints). Details: database.md.
The core domains and where they live
| Domain | What it is | Primary code | Primary tables | Doc |
|---|---|---|---|---|
| Identity / auth | signup, login, OTP, social login, sessions | classs/KvIdentityProvisioner.php, login.php, api/otp-verification.php | customer_master | 10-actors + auth (to add) |
| Users & roles | customer vs merchant vs staff vs admin; sub-profiles | classs/AdminUserManagerModule.php | customer_master, company_master | ../10-actors/README.md |
| Module control | which verticals are on/visible; enrollment types | — | kv_module_control (22), kv_module_registry (23) | module-registry.md |
| Membership | plans, gating, renewal | classs/Membership, kv_membership_plans (77) | kv_membership_plans, wallet_user_memberships | core (to add) |
| KYC / trust | verification, trust score | classs/ClaimKycModule.php, KooviraTrustScoreEngine.php | kyc_submissions, ai_trust_scores | core (to add) |
| Wallet | one wallet per user; store credit (KCredits) | classs/WalletModule.php | wallet_accounts (6), wallet_transactions (161) | ../40-financial/ |
| Money ledger | central double-entry order finance | classs/CommerceOrdersModule.php finance methods | kv_order_finance_master (63), kv_order_finance_entries (488) | central-finance-ledger.md |
| Commission | platform take per module | classs/CommissionEngineModule.php | platform_commission_settings (11), commission_transactions (92) | ../40-financial/ |
| Accounting | double-entry books | classs/AccountingEngine.php | accounting_journal | admin (to add) |
| Notifications | in-app/push/email/SMS/WhatsApp | classs/PushNotificationModule.php, KvMailService.php, KvWhatsAppCloud.php | fp_notify, email_queue | notifications (to add) |
| Modules (verticals) | commerce, food, hotels, … | classs/<X>Module.php | <x>_* tables | ../20-modules/README.md |
| Search / location | search, radar, geo | classs/KooviraLocation.php, forms/doaction_radar.php | postal_code_master (158,141), kv_ue_supply | search (to add) |
| AI / Bramha | AI assistant + services | classs/KvAiPlatform.php | kv_ai_services | ai (to add) |
| Developer platform | external REST APIs, OAuth | classs/DeveloperApiModule.php, api/developer/ | kv_api_endpoints, kv_api_scopes, kv_api_clients | devportal/index.php |
Row counts are 2026-09-06 snapshots. Tables marked "(to add)" are validated targets for the next documentation passes — see ../STATUS.md.
Corrected 2026-09-06 (re-audit, later same day):wallet_accounts/wallet_transactions/kv_order_finance_master/kv_order_finance_entrieswere re-counted against the live DB (this is an actively-written dev DB — concurrent QA/test-harness runs move these numbers within the same day, per ../METHODOLOGY.md's "date every count" rule); the earlier snapshot read 7 / 142 / 62 / 484, the numbers above are the live recount. Also corrected:postal_code_masterwas cited here as "153k" (an imprecise rounding, wrong even at write time) — the exact, live-verified count is 158,141, matching search-location-radar.md.
The three cross-cutting invariants
Everything in this platform obeys these. Violate them and money or isolation breaks.
- One wallet, wallet-first money. No module integrates a payment gateway directly. Money
flows Gateway → Koovira Wallet → module. Store credit is KCredits (1₹ = 1 KCredit, closed-loop).
- One order-finance ledger, polymorphic key. Every module's order money is recorded in
kv_order_finance_master/_entries keyed by (module_key, order_table, order_id) — because **order IDs are only unique within a module's own *_orders table** and collide across modules. Always match module + id, never id alone.
- Schema changes only through the migration system. The web/cron/deploy tiers cannot run DDL
(KVGuardedPDO). All DDL is padmin-gated.
How to read this documentation for a task
- "How does feature X work end-to-end?" → the module's
overview.md+ its flow file +code-map.md. - "What does table T store and who writes it?" →
90-database/tables/T.md(generated) + the owning
module's data-model.md.
- "What happens to money when …?" → ../40-financial/central-finance-ledger.md.
- "What breaks if I change this?" → the module page's Change-impact section.