Actors & Identity Model
Partially validated (2026-09-06). Rows marked 🟠 need a code/DB confirmation pass.
Koovira separates who you are (a person / login) from what capacity you are acting in (customer, a specific merchant type, staff, admin). One login can be both a customer and a merchant, and can hold sub-profiles.
The identity tables (validated names; confirm columns per feature)
customer_master— one row per profile, not per person. A person can have a parent profile
(parent_user_id = 0) plus sub-profiles (professional, dating). Counting people ≠ counting rows (a known trap: filter parent_user_id = 0 or overstate ~3×). This is the buyer/buyer_id, user_id referenced everywhere.
company_master— one row per business (55 columns, corrected 2026-09-06 — was cited as 57;
live SHOW COLUMNS count is 55; incl. primary_module, company_type, verified_badge). A merchant "acts as" a company. House rule: one account owns one company.
kv_module_registry— the enrollment type a company signs up under (see
../00-architecture/module-registry.md).
- Staff / sub-users, roles & permissions — managed via
classs/AdminUserManagerModule.phpand the
merchant staff screens. 🟠 exact permission tables to be documented in the auth pass.
Identity matrix (skeleton — fill/verify per capability)
| Identity | View | Create listing | Buy | Sell | Book | Manage business | Financial access | KYC required |
|---|---|---|---|---|---|---|---|---|
| Guest / anonymous | public only | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | — |
| Registered customer | ✔ | ✖ | ✔ (wallet-first) | ✖ | ✔ | ✖ | own wallet | at purchase-risk gates |
| Merchant / business owner | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | company wallet/settlement | ✔ (module-dependent) |
| Merchant staff / sub-user | ✔ | scoped | — | scoped | scoped | scoped by permission | scoped | inherits company |
| Service provider / freelancer | ✔ | ✔ (services/bids) | ✔ | ✔ (service) | ✔ | ✔ | escrow/wallet | ✔ |
| Property agent / builder | ✔ | ✔ (listings/projects) | — | ✔ | — | ✔ | membership/leads | ✔ (🟠 role-gate issues on record) |
| Delivery / courier / driver partner | assigned jobs | ✖ | — | — | — | partner panel | payouts | ✔ |
| Admin / super-admin (padmin) | all | all | — | — | — | all | all (commission, refunds, settlement) | n/a |
✔/✖ above are the intended model; each cell becomes authoritative only when tied to the actual permission check in code. Do not quote a cell as fact until the auth pass cites it.
To document next (auth & identity pass)
- Signup/login/OTP/social-login flows (each its own page, per the spec's §5).
- The permission/authorization matrix (§24) — page access, CRUD, publish, approve, financial.
- Identity switching (customer ↔ merchant), sub-profile activation
(TOGGLE_SUB_PROFILE), multi-module within one company.