morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
ea5fabaa7c
TorbatYar/docs/architecture/commercial-platform-architecture.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

8.9 KiB
Raw Blame History

Commercial Platform Architecture

Architecture / contracts only. No engines, migrations, APIs, or frontend portals are authorized by this document alone.
ADR: ADR-023
Phase: commercial-foundation (+ patches v1.1, v1.2)
Contract family version: commercial.v1.2
Status: ARCHITECTURE COMPLETE (implementation remains future work)

1. Purpose

The Commercial Platform Foundation defines how every TorbatYar offering is registered as a product, packaged into bundles, priced, subscribed, licensed, recommended, extended, automated (by reference), asset-backed, metadata-annotated, policy-governed, versioned, and activated for a tenant business.

It is a permanently extensible platform layer. Future products, assets, metadata keys, and policies are registry entries — architecture must not require modification when they are added.

2. Ownership

Concern Owner Storage (future) Notes
Platform Product Registry Core Platform (commercial) core_platform_db (future) Open-ended products
Capability Registry Core Platform (commercial) future Reusable capabilities
Automation Catalog Core Platform (commercial) future Not a product
Extension Registry Core commercial vocabulary; runtime owner per extension future No ownership conflicts
Asset Registry Core commercial vocabulary; payload owner per asset future Not product/bundle/capability
Metadata Registry Core Platform (commercial) future Unlimited keys
Policy Engine contracts Core Platform (commercial) future No engine in this wave
Dependency Graph Core Platform (commercial) future Refs only
Universal references / versioning Core Platform (commercial) future Stable IDs
Business Bundle catalog Core Platform (commercial) future Lightweight refs
Pricing Catalog Core Platform (commercial) future Independent of bundles
Subscription lifecycle Core Platform (commercial) future Refs to Payment billing shells only
License & entitlement projection Core Platform existing + future L1 commercial truth
Payment L2/L3 bundles & toggles Payment payment_db ADR-021
Experience / vertical L2 packs Owning service service DB Referenced, not owned here
Marketplace domain Marketplace product/service (when implemented) marketplace DB Independent; assets may declare marketplace readiness
Published Resources / Actions / Embed Experience + owning services per ADR-022 Unchanged
Identity membership / SSO Identity identity_access_db AuthN/AuthZ only
Accounting commercial contract Accounting accounting DB Opaque contract refs
Admin commercial UI Frontend (future) — Spec only

Forbidden ownership:

  • Frontend React as source of truth for products/bundles/pricing/assets
  • Payment owning Platform Product / Asset / Policy registries or Pricing Catalog
  • Experience owning subscription/license truth, Asset Registry, or foreign product connectors
  • Bundles/assets embedding implementations or pricing amounts
  • Treating Automation or Assets as PlatformProducts
  • Hardcoding closed product/capability/asset/policy enums in Core architecture
  • Marketplace owning Asset Registry vocabulary

3. Aggregate map (logical) — v1.2

CapabilityRegistry ◄──── PlatformProductRegistry ────► ExtensionRegistry
        ▲                        │
        │                        ├─ AutomationCatalog (packs; not products)
        │                        ├─ AssetRegistry (templates/themes/…; not products)
        │                        ├─ PolicyEngine (independent policies)
        │                        └─ MetadataRegistry (any target)
        │
        │              UniversalReference + RegistryVersioning
        │              DependencyGraph
        │
BusinessTypeCatalog
        │ recommends
        ▼
BusinessBundleVersion ──refs──► products, capabilities, automation packs,
                                extensions, assets, pricing, policies, plans
        │
        ▼
Subscription / License / Entitlement → ActivationPipeline (events)

4. Separation rules (normative)

  1. Pricing MUST NOT live inside bundle, product, or asset definitions — pricing refs / policies only.
  2. Products, assets, capabilities, policies, metadata keys are open-ended — registry entries only.
  3. Assets are not products, bundles, or capabilities.
  4. Automation is a catalog, not a product.
  5. Policies are independent — attach by target bindings; no evaluation engine in this wave.
  6. Metadata is unlimited-key additive JSON; ignore-unknown.
  7. Extensions declare publisher + runtime owner; assets declare publisher + optional payload owner.
  8. Marketplace is independent; products/assets declare compatibility or marketplace readiness only.
  9. Business Bundles remain lightweight — references only.
  10. Universal registry_object_id for cross-refs — no service-specific commercial SoT IDs.
  11. All registries support versions — registry-versioning.md.
  12. Recommendations never activate; activation is event-contracted.
  13. Frontend catalogs are generated from docs/YAML SoT.
  14. Future products require only registration + capabilities + docs + optional bundle mapping (v1.1 rules).
  15. Future assets/policies/metadata keys require only registry entries — no Core architecture changes.

5. Compatibility with existing ADRs

ADR Compatibility
ADR-001 Future commercial storage in Core DB only; no shared DB
ADR-002 Admin UI consumes contracts; backend owns truth
ADR-003 All commercial rows tenant-scoped when materialized
ADR-006 Activation / subscription transitions use outbox events
ADR-008 / onboarding-4 Workspace init remains Core/onboarding; commercial activation emits requests
ADR-020 / ADR-021 Payment L1 gated by Core; L2/L3 stay in Payment; billing shells reserved
ADR-022 Published Resources unchanged; assets/extensions may support presentation by ref
ADR-023 Base + v1.1 + v1.2 amendments; architecture complete for commercial foundation layer

6. Document map

Document Role
product-catalog.md PlatformProduct aggregates
product-registry.md Dynamic product registry + marketplace compatibility
capability-registry.md Reusable capabilities
automation-catalog.md Automation types & packs (not products)
extension-registry.md Widgets, actions, embeds, …
asset-registry.md Universal assets
asset-lifecycle.md Asset lifecycle states
asset-marketplace-contracts.md Asset distribution / marketplace readiness
metadata-registry.md Generic metadata
policy-engine-contracts.md Policy definitions
policy-targets.md Policy target bindings
registry-versioning.md Cross-registry versions
universal-reference-contracts.md Stable IDs
dependency-graph.md Requires / optional / conflicts / …
business-bundle-contracts.md Bundles
pricing-catalog.md Pricing
subscription-contracts.md Subscriptions
license-entitlement-contracts.md License / entitlement
activation-flow-contracts.md Activation events
commercial-compatibility-matrix.md Compatibility validation

7. Explicit non-goals

  • Backend feature engines, migrations, APIs, DB changes
  • Frontend portals
  • Implementing future products or Marketplace commerce
  • Policy evaluation engine, tax/discount engines
  • New roadmap implementation phases authorized by this patch alone

8. Architecture completeness

With v1 + v1.1 + v1.2 documented, the Commercial Platform Foundation is declared:

ARCHITECTURE COMPLETE

Implementation (storage, APIs, engines, admin UI, codegen) remains future registered work and is not authorized by accepting these contracts alone.