9fac160258
Add independent payment-service (port 8012, payment_db) with foundation licensing, BYO-PSP, merchant accounts, idempotent requests, callbacks, and immutable ledger. Co-authored-by: Cursor <cursoragent@cursor.com>
17 KiB
17 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. |
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. |
| Published Resource | Platform-wide public surface abstraction identified by publish_id (ADR-022). |
| Publish Target Registry | Logical catalog of Published Resources (publish_id, tenant_id, resource_type, resource_id, canonical_url, publish_status, visibility, owner_service). |
| publish_id | Stable cross-service key for Payment, Communication, Short Link, QR, Analytics, and future products — never Experience internal table ids. |
| Published Action | Extensible action on a Published Resource (action_key); owning service executes; Experience binds presentation (published-action-registry.md). |
| Public Access Policy | Composable access strategies for a Published Resource; Experience stores metadata only — Identity/Payment/Loyalty/Communication own challenges (public-access-contract.md). |
| Universal Embed | Contract for embedding Published Resources (iframe, SDK, widget, …) with security and analytics rules (embed-contract.md). |
| Website Builder (historical) | Scaffolded stub service — prefer Experience Platform for new page/site work (ADR-016). |
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). |
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. |
| 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). |
| Mandatory Phase Artifacts | Default engineering stack every implementation phase must deliver when applicable (mandatory-phase-artifacts.md). |
| Enterprise Completeness | Pre-close verification dimensions that must pass before Complete (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, ADR-019). |
| 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.