Koovira Developer Documentation — Single Source of Truth
👉 New here? START WITH PROJECT_SCOPE.md — the top-level orientation map (all sites, user types, admin tiers, modules, engines, DB, infra, prod-access limits, QA harness). It exists so a new session understands the whole system and finds the right deep doc without re-reading the codebase or the 1,797 tables. Drill into the folders below only for the area you touch.
The Developer Operating Manual for the Koovira platform. Intended to be published at developer.koovira.com (internal/engineering knowledge base). Codebase:C:\laragon\www\koovira_live_newLive DB (validated):koovira_newmasterdb_opt— MariaDB 10.11.14, 1,797 tables (probed 2026-09-06) Rule: every entry in this tree is validated against the actual code and database, not transcribed fromsystemflow/. See METHODOLOGY.md.
Why this exists
A developer who has never worked on Koovira should be able to take any feature and answer: what it does, who uses it, how a user reaches it, what happens on the backend, which tables and records change, what happens to money, what notifications fire, what breaks if it is modified, and what to test after a change. If a page here cannot answer those, that page is not done.
This is a living map, not a one-time dump. Where content can be generated from the live database (the data dictionary, row counts, foreign keys), it is generated by the scripts in _tools/ so it cannot silently drift from reality.
How this tree is organized
| Folder | Contents |
|---|---|
00-architecture/ | Platform architecture: bootstrap/config, database connection & conventions, the module registry, request lifecycle. Read this first. |
10-actors/ | Actor-based documentation — what each user type (customer, each merchant type, admin, staff, partner) can do. |
20-modules/ | One folder per module. Each follows _templates/module.template.md: overview, features, flows, data-model, state-machines, money-flow, code-map. |
40-financial/ | Cross-cutting money architecture: the central finance ledger, wallet, commission, escrow, settlement, refunds, GST. The financial source-of-truth reference. |
90-database/ | Data dictionary (generated), ER diagrams, table→feature reverse index. |
_templates/ | The canonical page templates. Copy these when adding a module or a table. |
_tools/ | Reusable validation + generation scripts (DB inspector, data-dictionary generator). |
Numeric prefixes keep the intended reading order stable and leave gaps (30, 50…) for sections still to be added (APIs, notifications, cron/background, business rules, QA).
Status & coverage
This documentation is being built module-by-module, each entry validated against code+DB. The current coverage is tracked in STATUS.md — check it before assuming a module is documented, and update it when you add a page.
Ground truth that everything else depends on
- Two module registries, different keys for the same concept.
kv_module_control(22 rows)
is the consumer/platform on-off + visibility control plane; kv_module_registry (23 rows) is the merchant enrollment type catalogue. They deliberately do not share keys — e.g. ecommerce↔merchant, cab_bike↔rides, real_estate↔realestate+builder, homeassist↔services. See 00-architecture/module-registry.md.
- Money has one ledger. Every module's order money is recorded in the central
kv_order_finance_master / kv_order_finance_entries double-entry ledger, keyed polymorphically by (module_key, order_table, order_id). See 40-financial/central-finance-ledger.md.
- Order IDs collide across modules. Because each module has its own
*_orderstable, an
order_id is only unique within a module. Always match module_key/order_table and order_id. This is why the finance ledger is keyed the way it is.
- The web tier cannot run DDL. All DB access goes through
KVGuardedPDO, which refuses
CREATE/ALTER/DROP/TRUNCATE/RENAME unless KV_SCHEMA_MIGRATION_MODE is set. See 00-architecture/bootstrap-and-config.md.
Relationship to existing docs
systemflow/(721 files) anddocs/(147 files) are the working history — audits, session
logs, roadmaps. They are valuable but time-stamped and can be stale. This tree supersedes them as the authoritative reference: where they disagree with code, code wins and the drift is noted here.
devportal/index.phpis the public, external API portal for third-party developers
(reads kv_api_endpoints / kv_api_scopes live). This tree is the internal engineering manual. Both can live under developer.koovira.com; they answer different questions.
Last validated: 2026-09-06.