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** | **Platform:** a user with a membership row linking them to a Tenant. **Sports Center:** see Member (Sports) — do not conflate. |
| **Platform Member** | Preferred unambiguous term for a user linked to a Tenant via `tenant_memberships`. |
| **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. |
| **Loyalty Program** | Tenant-scoped loyalty program configuration (Loyalty-owned). |
| **Loyalty Member** | Loyalty-owned membership record in a program (distinct from Platform Member / Sports Member). |
| **Membership Lifecycle** | Loyalty state machine: enroll/activate/renew/freeze/resume/cancel/expire/transfer. |
| **Loyalty Member** | Enrolled participant in a Loyalty Program; belongs to exactly one Tenant. |
| **Membership Tier** | Ranked level within a Loyalty Program. |
| **Point Account** | Loyalty points account shell; balances come only from immutable ledger entries. |
| **Communication Platform** | Independent shared service owning outbound messaging, providers, templates, queue, OTP, and delivery tracking. |
| **Provider Failover** | Automatic switch to the next priority provider when send fails or circuit is open. |
| **Dynamic Contact Source** | API-configured resolver that fetches destinations at send time without copying business-module rows. |
| **Order** | Purchase intent/fulfillment record (ecommerce/restaurant). |
| **Inventory** | Stock levels for sellable items. |

## Sports Center

| Term | Definition |
| --- | --- |
| **Member (Sports)** | Enrolled athlete or club customer profile in Sports Center (`members` table) — not a Platform Member and not a Loyalty Member. |
| **Membership (Sports)** | Active enrollment instance linking a Member to a Membership Type from the catalog; supports freeze/activate/cancel. |
| **Family Member (Sports)** | Household/relationship link under a Sports Member (may optionally reference another Member). |
| **Emergency Contact** | Contact person recorded for a Sports Member for emergency use. |
| **Medical Information (Sports)** | Privacy-aware clearance/notes shell for a Sports Member — not an EHR; binaries via Storage refs. |
| **Membership Card** | Physical/digital/QR card issued to a Sports Member (payload strings only until attendance devices). |
| **Digital Membership** | Digital pass / wallet shell for a Sports Member (`pass_code` + optional token/deep-link refs). |
| **Waiver** | Liability/consent record for a Sports Member; sign action stores signature/file refs. |
| **Coach** | Sports Center staff record who coaches members/sessions (Sports Center–owned). |
| **Trainer** | Synonym/role variant of Coach; prefer **Coach** in APIs unless a distinct trainer role is modeled. |
| **Program** | Structured training program definition owned by Sports Center (not a Loyalty Program). |
| **Workout** | Concrete workout definition or assigned workout instance under a Program or coach plan. |
| **Attendance** | Check-in/check-out or presence record for a member at a facility/session. |
| **Booking** | Reservation of a facility, court, session, or equipment slot. |
| **Facility** | Physical sports space unit (building area, room, hall) owned by Sports Center. |
| **Court** | Bookable facility subtype (e.g. tennis/futsal court). |
| **Session** | Scheduled time-bound activity (class, training, rental) that may be booked or attended. |
| **Locker** | Assignable locker unit or locker status record in Sports Center. |
| **Access Device** | Hardware or logical reader used for attendance/access control (adapter-owned credentials stay out of other services). |
| **Competition** | Organized contest or tournament record owned by Sports Center. |
| **Membership Plan** | Commercial definition of sports membership benefits/duration (Membership Types). |
| **Package** | Bundled sports offering (sessions/classes/services) sold under Membership Types. |
| **Renewal** | Extending an active sports Membership for a new period. |
| **Freeze** | Temporary suspension of a sports Membership without full cancellation. |
| **Transfer** | Moving a sports Membership between eligible members/accounts per business rules. |
| **Sports Event** | Calendar/competition event in Sports Center — distinct from domain/integration **Events** on the bus. |


## Delivery & Fleet Platform

| Term | Definition |
| --- | --- |
| **Delivery Platform** | Independent shared logistics service (`delivery`) owning drivers, fleet, dispatch, routing, tracking, POD, and settlement intents — commercial product **Torbat Driver**. |
| **Torbat Driver** | Commercial product name for the Delivery & Fleet Platform. |
| **Driver (Delivery)** | Courier/operator profile owned by Delivery — not a Platform Member and not a Sports Coach. |
| **Fleet** | Group of vehicles/drivers managed as an operational unit in Delivery. |
| **Vehicle Type** | Catalog class of vehicle (bike, car, van, …) with capability flags. |
| **Dispatch** | Assignment of delivery jobs to drivers/vehicles. |
| **Delivery Job** | Logistics work unit referenced by external vertical order IDs — Delivery does not own the vertical order aggregate. |
| **Working Zone** | Geo/operational area where drivers may accept jobs. |
| **Shift (Delivery)** | Scheduled working window for a driver. |
| **Multi Pickup / Multi Drop** | Route with multiple pickup and/or drop stops on one job/route. |
| **Proof of Delivery (POD)** | Evidence that a drop was completed (signature/photo/code refs). |
| **Customer Tracking** | Tokenized tracking view for end customers — distinct from dispatcher tracking. |
| **Merchant Connector** | API/event contract for verticals to request logistics without embedding Delivery logic. |
| **Settlement (Delivery)** | Intent to settle driver/merchant amounts; journals only via Accounting Posting Engine. |
| **Message Delivery** | Communication-owned SMS/email/push delivery status — **not** physical logistics. |

## Experience Platform

| Term | Definition |
| --- | --- |
| **Experience Platform** | Independent shared digital experience service (`experience`) owning sites, pages-as-resources, versioned components, themes, layouts, templates, forms, SEO/PWA shells, bundles, and widgets — commercial product **Torbat Pages**. |
| **Torbat Pages** | Commercial product name for the Experience Platform. |
| **Page Resource** | First-class tenant-scoped page entity with identity, lifecycle, and permissions — not a CMS blob owned by a vertical. |
| **Component (Experience)** | Versioned building block composed into pages; versions are immutable once published. |
| **Theme (Experience)** | Replaceable visual pack applied to sites/pages without rewriting page trees. |
| **Layout (Experience)** | Dynamic composition structure for placing components. |
| **Template (Experience)** | Starter definition used to instantiate sites/pages of a given type. |
| **Page Type** | Classification of page purpose (landing, mini site, digital menu, bio link, portfolio, blog, QR, …). |
| **Experience Bundle** | Licensed capability pack (e.g. Digital Menu, Bio Link, Custom Domain) gated via entitlement. |
| **Widget (Experience)** | Embeddable experience surface for consumer apps/sites. |
| **Consumer Connector (Experience)** | API/event contract for verticals to bind entity refs into pages without embedding Experience logic. |
| **Website Builder (historical)** | Scaffolded stub service — prefer Experience Platform for new page/site work ([ADR-016](architecture/adr/ADR-016.md)). |

## Hospitality Platform

| Term | Definition |
| --- | --- |
| **Hospitality Platform** | Independent F&B operations service (`hospitality`) owning venues, menus, tables, bundles, and feature toggles — commercial product **Torbat Food**. |
| **Torbat Food** | Commercial product name for the Hospitality Platform. |
| **Venue** | Root hospitality unit for a tenant (cafe, restaurant, bakery, cloud kitchen, …). |
| **Venue Format** | Configurable classification of a venue — not a hardcoded business engine. |
| **Digital Menu Catalog** | Menu depth layer: allergens, modifiers, availability windows, media refs, localizations (Phase 12.1). |
| **Modifier Group** | Selection-rule container (size/extras) linked to menu items; not a POS engine. |
| **Availability Window** | Time-of-day / weekday window scoping menu, category, or item availability. |
| **Menu Media Ref** | Storage `file_ref` pointer for menu imagery; Hospitality does not own blobs. |
| **Bundle (Hospitality)** | Licensable capability pack (e.g. Digital Menu, POS Lite, Kitchen) gated via entitlement / tenant activation. |
| **Feature Toggle (Hospitality)** | Per-tenant/venue capability flag used for discovery and gating. |
| **Dining Table** | Seating/table shell — QR/ordering engines come in later phases. |
| **Restaurant (historical)** | Scaffold alias — prefer Hospitality Platform ([ADR-017](architecture/adr/ADR-017.md)). |

## 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. |
| **AI Development Framework** | Permanent docs under `docs/ai-framework/` governing AI-assisted implementation (process — not the product AI Assistant). Also called **Enterprise Development Framework** after [ADR-018](architecture/adr/ADR-018.md). |
| **Enterprise Development Framework** | Alias for the upgraded AI Development Framework: production-ready phases by default via DoD, mandatory artifacts, completeness, and boundary rules. |
| **Definition of Done (phase)** | Mandatory exit checklist: feature-complete for the phase boundary; CRUD never sufficient ([definition-of-done.md](ai-framework/definition-of-done.md)). |
| **Mandatory Phase Artifacts** | Default engineering stack every implementation phase must deliver when applicable ([mandatory-phase-artifacts.md](ai-framework/mandatory-phase-artifacts.md)). |
| **Enterprise Completeness** | Pre-close verification dimensions that must pass before Complete ([enterprise-completeness.md](ai-framework/enterprise-completeness.md)). |
| **Enterprise Phase Discovery** | Mandatory pre-implementation inventory of roadmap, architecture, boundaries, prior handover, and existing code/APIs/domain/events/permissions/aggregates/tests/docs; derives missing current-phase capabilities ([enterprise-phase-discovery.md](ai-framework/enterprise-phase-discovery.md), [ADR-019](architecture/adr/ADR-019.md)). |
| **Boundary Rules** | Hard constraints: no foreign ownership, no logic duplication, no cross-DB access, API/Events/Providers only, no future-phase pull-forward. |
| **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)
- [AI / Enterprise Development Framework](ai-framework/README.md)
- [Enterprise Phase Discovery](ai-framework/enterprise-phase-discovery.md)
- [Definition of Done](ai-framework/definition-of-done.md)
- [ADR-018](architecture/adr/ADR-018.md)
- [ADR-019](architecture/adr/ADR-019.md)
- [Sports Center Roadmap](sports-center-roadmap.md)
- [Delivery Roadmap](delivery-roadmap.md)
- [Experience Roadmap](experience-roadmap.md)
- [Hospitality Roadmap](hospitality-roadmap.md)