TorbatYar/docs/glossary.md

# Glossary

Canonical definitions for TorbatYar. Prefer these terms in docs and code comments.

## Platform & Tenancy

| Term | Definition |
| --- | --- |
| **Tenant** | A customer workspace/organization on the platform. Owns domains, branding, memberships, and subscriptions. |
| **Workspace** | Product synonym for an operational Tenant after onboarding. |
| **Organization** | Business entity represented by a Tenant (not a separate table today). |
| **Member** | A user with a membership row linking them to a Tenant. |
| **Tenant Membership (Core)** | `core_platform_db.tenant_memberships` — source of truth for workspace roles/ownership. |
| **Tenant Membership (Identity)** | `identity_access_db.tenant_memberships` — SSO listing membership; not operational authz. |
| **Workspace Activation** | Completing onboarding so tenant moves to `active` with `onboarding_completed=true`. |
| **Current Tenant** | `users.current_tenant_id` — workspace selected for the session context. |
| **Domain** | Hostname mapped to a tenant (subdomain or custom). |
| **Primary Domain** | Domain marked `is_primary` for the tenant. |
| **White Label** | Per-tenant branding (colors, logo, favicon, name) applied at runtime. |
| **Platform Base Domain** | `PLATFORM_BASE_DOMAIN` (e.g. `torbatyar.ir`) used to mint `{slug}.{base}`. |

## Identity & Access

| Term | Definition |
| --- | --- |
| **Identity** | Who the actor is (Keycloak subject + Core/Identity profiles). |
| **Platform User** | User recorded in Core `users` (mobile-required). |
| **SSO** | Central Keycloak OpenID Connect login for staff. |
| **OTP** | One-time password sent via SMS for mobile verification/login. |
| **Keycloak Sub** | Stable IdP subject id stored as `keycloak_sub`. |
| **JIT Provisioning** | Creating/linking Core user from Keycloak JWT on first resolve. |
| **Handoff** | One-time session token from Keycloak theme mobile flow redeemed by frontend. |
| **BFF** | Backend-for-frontend (Identity token exchange). |
| **Role** | Named authorization level (platform/tenant roles). |
| **Permission** | Fine-grained allow rule (future trees; today largely role + entitlement). |
| **Entitlement** | Plan/feature gate: whether a tenant may use a feature_key. |
| **Feature Key** | `{service}.{resource}.{action}` string checked by Core. |
| **Internal Service Token** | Machine credential for service-to-service calls. |

## Modular Product

| Term | Definition |
| --- | --- |
| **Module** | Installable/activateable product capability with clear DB and API ownership. |
| **Service** | Deployable backend unit implementing one or more modules. |
| **Provider** | External vendor adapter (SMS, payment, storage, AI model, tax). |
| **Service Registry** | Core table of internal services (`service_key`, base URL, health). |
| **Module Registry** | Core table + docs inventory of modules and activation. |
| **Subscription** | Tenant’s plan binding (`tenant_subscriptions`). |
| **Plan** | Packaged set of features/limits (e.g. FREE, STARTER). |

## Accounting (future)

| Term | Definition |
| --- | --- |
| **Ledger** | Books of account for a tenant. |
| **Account** | Chart-of-accounts node (planned 4-level structure). |
| **Journal** | Collection of journal entries. |
| **Journal Entry** | Double-entry header document. |
| **Journal Line** | Debit/credit line under an entry. |
| **Voucher** | Business document that may result in postings. |
| **Posting** | Act of writing validated lines to the ledger. |
| **Posting Engine** | Sole authorized component to create journal entries. |
| **Cost Center** | Analytical dimension for costs. |
| **Project** | Analytical dimension for project accounting. |

## CRM / Commerce / Ops

| Term | Definition |
| --- | --- |
| **Lead** | Prospective customer record (CRM-owned). |
| **Contact** | Person record in Sales CRM. |
| **Organization (CRM)** | Business account / company record in Sales CRM (not the platform Tenant). |
| **Opportunity** | Qualified sales opportunity in a pipeline. |
| **Pipeline / Stage** | Configurable sales process steps. |
| **Sales Playbook** | Versioned sales checklist assigned to pipeline/opportunity. |
| **Sales Forecast** | Rule-based pipeline/weighted/committed forecast (no ML). |
| **Sales Activity** | Call, meeting, task, email, follow-up, demo, or custom activity. |
| **Sales Timeline** | Immutable CRM collaboration event stream. |
| **Quote (Sales)** | CRM sales quote — not an accounting invoice. |
| **Order** | Purchase intent/fulfillment record (ecommerce/restaurant). |
| **Inventory** | Stock levels for sellable items. |

## Technical

| Term | Definition |
| --- | --- |
| **Database-per-Service** | Each service owns its DB; no cross-DB queries. |
| **Outbox / Inbox** | Reliable event publish/consume tables. |
| **Event Envelope** | Standard event metadata wrapper. |
| **API-First** | Contracts precede UI implementation. |
| **ADR** | Architecture Decision Record. |
| **Phase** | Time-boxed delivery with completion gate. |
| **Tenant-Aware** | Request/data path always scoped to a tenant. |
| **Audit Log** | Immutable-ish record of who did what, when. |

## Phase Numbering Note

Internal docs: **فاز ۳** = OTP + Tenant Management; **فاز ۴** = Onboarding/Workspace Activation. Some briefs labeled onboarding as “Phase 3”. Always disambiguate using [progress.md](progress.md).

## Related Documents

- [Module Registry](module-registry.md)
- [Provider Registry](provider-registry.md)
- [Architecture Overview](architecture/architecture.md)