e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
9.6 KiB
9.6 KiB
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.