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. |

## 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). |
| **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 Development Framework](ai-framework/README.md)
- [Sports Center Roadmap](sports-center-roadmap.md)