Koovira — Project Scope & Orientation Map

Purpose: the single entry point for a new session. Read THIS first to understand the whole system, then drill into the linked deep docs only for the area you're touching — so you don't re-read the codebase or 1,797 tables to get oriented.

Scale (2026-09): ~1,797 DB tables · ~541 classes in classs/ · 15 merchant module types · ~400 merchant routes · multi-tenant, multi-module, one login = many capacities.

Last mapped: 2026-09-26. Treat cells marked 🟠 as "verify against code before quoting."

0. How to use this map

1. Identify the actor (§2) and module (§4) your task touches.
2. Open the matching deep doc under developer/docs/ (paths given per section).
3. For DB, use developer/docs/90-database/INDEX.generated.md (every table) instead of SHOW TABLES.
4. For infra/deploy/prod access limits, see §7 (this saves the most time).

1. Sites & products (this account's estate)

Company: Trishara Ventures LLP (never rename in brand sweeps).

2. Actors / user types → deep: developer/docs/10-actors/

Koovira separates who you are (a login) from the capacity you act in. One login can be customer + merchant + hold sub-profiles.

• customer_master — one row per profile, not per person. parent_user_id = 0 is the primary

profile; sub-profiles (professional, dating) hang off it. Counting people ≠ counting rows — filter parent_user_id = 0 or you overstate ~3×. This is user_id/buyer_id referenced everywhere.

• profile_type: social · professional · dating (+ general).
• user_type: general/customer, merchant, plus internal (seed_reviewer, …).
• Entity separation (do not conflate): USER ≠ TALENT ≠ EVENT ENROLLMENT ≠ CONTESTANT — each is

its own entity with a configurable attribute master. (Founder rule.)

• company_master — one business (~55 cols; primary_module, company_type, verified_badge).

House rule: one account owns one company; a company activates many modules.

• Staff / sub-users — classs/AdminUserManagerModule.php + merchant staff screens; scoped by permission.

Identity/permission matrix (guest → customer → merchant → staff → provider → agent → driver → admin) is in 10-actors/README.md and 10-actors/permissions-matrix.md. Authorization is layered gates, not one ACL.

3. Admin model → deep: developer/docs/26-admin/, panel at /padmin

• core_admin_system — platform admins. Tiers (founder model): **super-admin → territory admin →

sub-admin**, each with capped rights and a department_key. MFA on the founder's super-admin (kooviraindia@gmail.com / admin@koovira.com).

• Login: koovira.com/padmin/login.php. Merchant console: koovira.com/merchant/ (gated via login.php).
• Config lives in the DB (env = bootstrap only): ai_platform_settings, admin_global_settings, etc.
• Key admin classes: AdminUserManagerModule, AdminSettingsModule, AdminPanelSecurityModule,

AdminPriceManagerModule, classs/admin/* (server ops, tech ops).

4. Modules

4a. Merchant module types (a company activates one+; merchant/includes/nav_registry.php)

cab · campus · classifieds · delivery_partner · ecommerce · events · fitness · food · freelance · hotels · jobs · pharmacy · realestate · services · truck

Each has a merchant desk (Today / Orders / Money / Customers / Marketing / Set-up panes). Merchant-suite architecture + nav rules: developer/docs/25-merchant-suite/. Nav is generated — never hand-edit the registry; regenerate with tools/qa/merchant_nav/gen_registry.py; gate tools/qa/test_merchant_nav_architecture.php must stay green.

4b. Consumer/product surfaces ("verses") and functional modules → developer/docs/20-modules/<x>/

5. Core engines & systems (grouped; classs/ ≈ 541 classes) → developer/docs/30-core/, 50-errors/, 60-registry/

• Auth/identity: AuthModule, AdminUserManagerModule.
• Commerce: CommerceOrdersModule, CommerceReturnsModule, CommerceRoutingEngine,

CommerceSettlementModule, CommissionEngineModule, CouponModule, CategoryMappingModule.

• Logistics/TMS: classs/logistics/* (JourneySetupEngine, …), courier engines; the whole TMS is

exercised by tools/qa/tms_uat_all.php.

• Cases / self-healing AI ops: classs/cases/CaseResolutionEngine.php, classs/cases/CaseBrain.php,

classs/situations/packs/bramha.php (BramhaSituationPack detectors). Bramha = the AI ops brain (detect → investigate → propose; never moves money/books without approval).

• AI (Bramha/Bramha): AIEngineModule, AIRecommendationEngine, AITaggingEngine,

apiportal/ (developer API + AI portal). NOTE brand naming (Bramha ↔ Bramha) has been swept both ways — check current constants in apiportal/inc/brand.php before assuming.

• Media Asset Engine: ffmpeg/tesseract/pdftotext/soffice/ImageMagick — CLI/server only; sharp

thumbnails; upload-rights declaration; report-a-violation. See media pipeline note. Web code that shells out is inventoried in the item-5 hardening audit (do NOT blanket disable_functions the web pool).

• Location: classs/KooviraLocation.php (Valhalla routing + Nominatim geocode + Google fallback).
• Notifications: NotificationCatalog, reminder model + folds (test_kv_reminder_*).

6. Financial system → deep: developer/docs/40-financial/

• Wallet-first: WalletModule (wallet_transactions), per-company + per-user.
• Ledger/accounting: AccountingJournalModule / AccountingEngine (merchant_settlement_ledger,

accounting_journal), kv_order_finance_master.

• Settlements & payouts: shared settlements + per-module payout desks (courier/cab/truck/…).
• Gateway: Razorpay (koovira + xeswear). Invoices where GST > 0 (orders_master).
• Known shape work: Finance-overview-vs-ledger unification (40-financial/), central-finance-ledger.

7. Infra, deploy & PROD ACCESS LIMITS (read before any prod work — saves the most time)

• Prod: one GCP VM 34.100.139.124, user sharadchandra, key ~/.ssh/koovira_gcp_vm.pem,

passwordless sudo. Sites under /var/www (/var/www/koovira, /var/www/xeswear.com, …). nginx (Apache/.htaccess is DEAD on prod), vhosts in /etc/nginx/sites-available. GoDaddy DNS.

• DB: koovira_newmasterdb_opt — local MAMP 127.0.0.1:3306 root/root; prod via sudo mysql on the VM.

Migrations ONLY via tools/migrate.php up <file> (raw prod UPDATEs are blocked). Never rsync any .env*.

• Deploy pattern: stage → scp to /tmp on VM → sudo cp into docroot with www-data ownership

→ verify → auto-revert. (Old deploy_*.sh scripts point at the retired Azure box — ignore them.)

• ⚠️ Claude-session classifier limits (not user-overridable in chat): a Claude session is BLOCKED from

prod SSH ("Production/Remote Shell Writes"), from editing .env/nginx/cron/ufw, and from modifying its own permission settings ("Self-Modification"). To let a session run prod commands, the USER must add a Bash(ssh *)-style allow-rule to ~/.claude/settings.json (and that file must be valid JSON). Otherwise hand the user a self-verifying, auto-reverting script to run. This is why prod changes come as scripts.

8. QA / testing harness (how to verify without re-reading code)

• Full TMS/platform UAT: tools/qa/tms_uat_all.php --base=<url> (163 suites / 6k+ assertions; suites

self-rollback; prod adds hygiene). Prod: KOOVIRA_ENV=production sudo -u www-data php tools/qa/tms_uat_all.php --base=https://koovira.com.

• All suites: tools/qa/test_*.php (251). NOTE: running them all against the SHARED local DB pollutes

the QA company (id 3) → cross-suite false failures; the CLEAN signal is the prod run.

• Merchant nav gate: tools/qa/test_merchant_nav_architecture.php (must stay 40/0).
• Prod QA accounts: customer qa.one@koovira.qa (customer_master #96; also Bramha/Gym OAuth); tosset

employer demo.casting.qa@tossettest.in; padmin = founder's MFA super-admin. No dedicated merchant QA account on prod yet (create via tools/qa/_qa_fixture_company.php, never company 3). Passwords are not in the repo (bcrypt in DB / founder's go-live audit).

9. Build standards (Koovira house rules)

• Bootstrap 5.3 local (no CDN); one page = one job; CLI migrations; KVAlert for alerts;

no inline CSS/JS in pages (gated). UI: Netflix-quality but fix its pain points (no autoplay-on-hover, no layout shift, real search, accessible). Config in DB; env = bootstrap only. SEO/SMO via page registry.

10. Known open items (as of 2026-09-26)

• Bramha box_health hour-rule bug: classs/situations/packs/bramha.php:178 checks

ranRecently(...,'box_health','platform',1,60) (entity type platform) but the case is opened via openCaseFor(...,'moderation_box',1) (entity type moderation_box) — mismatch lets a 2nd case open within the hour. Only genuine failure in the prod UAT. Fix + verify on prod.

• Merchant nav item-6 polish (page merges/renames) — product decisions pending.
• Connector category/field mapping (kv_external_category_map written but unread vs external_category_staging) — needs a one-system decision.
• Security hardening (item 5): ship /uploads/*.php deny + open_basedir first; DEFER blanket disable_functions (breaks 30+ media/AI/resume/OCR modules — see the hardening audit).