morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
0d424c500a
TorbatYar/docs/architecture/adr/ADR-023.md
Mortezakoohjani 091b33a638 feat(platform): finalize commercial runtime, platform shell and hospitality production frontend 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-28 20:39:10 +03:30

12 KiB
Raw Blame History

ADR-023: Commercial Platform Foundation (Business Bundles, Pricing, Subscriptions)

Field Value
Status Accepted
Date 2026-07-28
Deciders Platform Architecture
Supersedes —
Superseded by —
Extends ADR-020, ADR-021, ADR-003, ADR-008

Context

Product Integration Wave 1 introduced a frontend-only commercial bundle catalog (frontend/lib/business-bundles.ts). Payment defines service-local L2 bundles (ADR-021). Experience, Hospitality, and other services similarly use service-owned capability packs.

Without a platform-level commercial abstraction:

  1. Bundle definitions drift between React, Payment, and verticals.
  2. Pricing is mixed into marketing copy or service schemas.
  3. Subscription, license, and entitlement semantics diverge across Identity, Core, Payment, and Accounting.
  4. Business-type recommendations cannot be governed as contracts.
  5. Activation of a tenant workspace cannot be sequenced as durable, cross-service events.

The platform needs a Commercial Foundation: architecture and contracts only — no engines, migrations, or product modules in this decision.

Decision

  1. Introduce Business Bundle Architecture as a platform concept owned by Core Platform commercial layer — not frontend-only, not Payment-only, not Experience-only.
  2. Canonical aggregates (logical; no schema authorized by this ADR alone):
    • BusinessBundleDefinition
    • BusinessBundleVersion
    • BusinessBundleService
    • BusinessBundleModule
    • BusinessBundleFeature
    • BusinessBundlePricingReference (opaque refs only — pricing does not live inside bundles)
    • BusinessBundleRecommendationRule
    • BusinessBundleVisibility
    • BusinessBundleLifecycle
    • BusinessBundleMetadata
  3. Introduce an independent Pricing Catalog (monthly, yearly, usage, trial, promotional, enterprise quote; future regional/tax/coupon/discount/reseller) as separate contracts.
  4. Introduce Subscription contracts (Subscription, SubscriptionPlan, SubscriptionItem, SubscriptionLicense, status/period/renewal/cancellation/grace) owned commercially by Core — Payment may later attach billing shells via existing reserved contracts; Payment does not own platform subscription lifecycle.
  5. Introduce License & Entitlement contracts (service / module / feature entitlement, quota, usage limits, capability flags, tenant visibility) integrating Identity, Payment, Accounting, Experience, CRM, Communication by reference only.
  6. Introduce a Business Type Catalog and rule-based Recommendation contracts (no AI).
  7. Document an Activation Flow as event contracts only (Business Created → … → Dashboard Generated).
  8. Specify Admin Portal screens for commercial management — no frontend implementation in this phase.
  9. Source of truth for business bundles and commercial catalogs is docs/reference/* (and optional YAML catalogs). Frontend TypeScript catalogs MUST become generated artifacts; manual React maintenance of commercial truth is forbidden going forward.
  10. Distinguish clearly:
    • BusinessBundle* = cross-product commercial packaging (this ADR)
    • Payment / Experience / Hospitality L2 bundles = service-owned capability packs (ADR-021, vertical ADRs) — referenced by Business Bundles, never absorbed
  11. This ADR is architecture + contracts + admin specification only. No backend feature engines, migrations, APIs, databases, customer portals, or future product foundations (QR, Short Links, Booking, Torbat Credit, Payment 14.6+, Experience FE-11.6+, Marketplace) are authorized.

Consequences

Positive

  • One commercial vocabulary for every product
  • Pricing and packaging remain separable
  • Frontend and services consume the same contracts
  • Activation is event-sequenced without premature implementation
  • Compatible with existing Payment L1/L2/L3 and Published Resource models

Negative

  • Future implementation must introduce Core commercial storage carefully
  • Existing frontend catalog must be regenerated from docs (transition debt)

Neutral

  • Completed Payment 14.0–14.5, Experience FE-11.0–11.5, and Product Integration Wave 1 UX remain unchanged
  • Service L2 bundles continue to be owned by their services

Alternatives Considered

  1. Keep React as catalog source of truth — rejected (duplicates, no admin governance, violates ADR-002 commercial governance).
  2. Put commercial bundles inside Payment — rejected (Payment owns payment capability packs only; commercial packaging is cross-product).
  3. Put pricing inside BusinessBundleDefinition — rejected (blocks regional/tax/coupon evolution and plan reuse).
  4. AI recommendation engine now — rejected (out of scope; rule contracts only).

Related Documents

Amendment — Commercial Foundation v1.1 (2026-07-28)

Field Value
Status Accepted (additive amendment)
Date 2026-07-28
Amends This ADR (decisions 1–11 remain in force)

Context

The v1 Commercial Foundation packaged businesses via bundles, pricing, subscriptions, and licenses, but did not yet provide a permanently extensible product / capability / automation / extension model. Without it, each future commercial product risks requiring Core architecture edits.

Additional decisions (additive)

  1. Introduce an open Platform Product Catalog and Dynamic Product Registry (PlatformProduct* aggregates). Every commercial offering is a PlatformProduct. Product lists are never hardcoded in architecture — unlimited future products via registry entries only.
  2. Introduce Marketplace Compatibility declarations on products (requires_marketplace, marketplace_optional, marketplace_compatible, publisher/consumer/plugin/extension/integration roles). Marketplace remains an independent product.
  3. Introduce an Automation Catalog (types + packs). Automation is not a PlatformProduct.
  4. Introduce an Extension Registry (widgets, blocks, actions, embeds, connectors, templates, reports, dashboards, themes, integrations, validators, automation packs, AI skills, … — open kinds). No ownership conflicts: publisher product + runtime owner service.
  5. Introduce a Capability Registry. Capabilities are independent reusable objects; products consume them; bundles reference them; definitions are never duplicated.
  6. Business Bundles (v1.1) MUST reference products, capabilities, automation packs, extensions, pricing, and subscription/license plan refs — never embed implementations. Legacy service/module/feature refs remain valid.
  7. Future Product Rules: adding a future product requires only (1) PlatformProduct registration, (2) capability declaration, (3) documentation, (4) optional bundle mapping — no Core architecture changes.
  8. Introduce a Commercial Dependency Graph (requires, optional, conflicts, recommended, deprecated, replacement).
  9. This amendment remains architecture + contracts only. It does not authorize backend/frontend/DB/API implementation or any future product engines.

Related Documents (v1.1)

Amendment — Commercial Foundation v1.2 (2026-07-28)

Field Value
Status Accepted (additive amendment)
Date 2026-07-28
Amends This ADR (decisions 1–20 remain in force)

Context

v1.1 made products, capabilities, automation, and extensions permanently extensible. The foundation still needed reusable assets, open metadata, and independent policy contracts, plus universal versioning and references, to close the commercial architecture layer without implementing engines.

Additional decisions (additive)

  1. Introduce a Universal Asset Registry. Assets are reusable commercial resources (templates, themes, libraries, packs, …). Assets are not products, bundles, or capabilities. Asset types are open-ended.
  2. Document Asset Lifecycle states: draft, review, published, deprecated, archived, deleted, versioned, cloned, installed, shared, marketplace_ready (plus install/share records).
  3. Introduce a Metadata Registry: every registry object may carry an open attribute bag (slug, tags, labels, industry/locale/country/language/currency/timezone/brand/owner/support_level/release_channel/icon/color/seo/marketing/visibility/documentation/beta/deprecated/custom_attributes, …). Unlimited future keys; no schema change required.
  4. Introduce Policy Engine contracts (independent policies: eligibility, licensing, commercial, regional, pricing, tax, promotion, discount, activation, feature visibility, capability access, quota, marketplace rules, compliance, security, support, trial, renewal, expiration, …). No evaluation engine in this amendment.
  5. Policies may target open kinds: product, bundle, capability, subscription, license, tenant, workspace, business type, country, region, industry, automation, asset, metadata, and future object types.
  6. Document Asset Marketplace distribution modes (installed, shared, cloned, purchased, free, enterprise only, private, organization only, marketplace ready) without implementing Marketplace.
  7. All registries support versions via shared versioning contracts.
  8. Every registry object receives a stable universal registry_object_id — commercial cross-refs must not use service-specific identifiers as SoT.
  9. With decisions 1–28 documented, the Commercial Platform Foundation is declared ARCHITECTURE COMPLETE. Implementation requires future registered phases and is not authorized by this ADR alone.

Related Documents (v1.2)