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 (future)

Term	Definition
Lead	Prospective customer record.
Opportunity	Qualified sales opportunity in a pipeline.
Pipeline / Stage	Configurable sales process steps.
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.

Related Documents

• Module Registry
• Provider Registry
• Architecture Overview