TorbatYar/docs/architecture/commercial-platform-architecture.md

# Commercial Platform Architecture

> **Architecture / contracts only.** No engines, migrations, APIs, or frontend portals are authorized by this document alone.  
> ADR: [ADR-023](adr/ADR-023.md)  
> 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](adr/ADR-021.md) |
| 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](../reference/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](../reference/product-catalog.md) | PlatformProduct aggregates |
| [product-registry.md](../reference/product-registry.md) | Dynamic product registry + marketplace compatibility |
| [capability-registry.md](../reference/capability-registry.md) | Reusable capabilities |
| [automation-catalog.md](../reference/automation-catalog.md) | Automation types & packs (not products) |
| [extension-registry.md](../reference/extension-registry.md) | Widgets, actions, embeds, … |
| [asset-registry.md](../reference/asset-registry.md) | Universal assets |
| [asset-lifecycle.md](../reference/asset-lifecycle.md) | Asset lifecycle states |
| [asset-marketplace-contracts.md](../reference/asset-marketplace-contracts.md) | Asset distribution / marketplace readiness |
| [metadata-registry.md](../reference/metadata-registry.md) | Generic metadata |
| [policy-engine-contracts.md](../reference/policy-engine-contracts.md) | Policy definitions |
| [policy-targets.md](../reference/policy-targets.md) | Policy target bindings |
| [registry-versioning.md](../reference/registry-versioning.md) | Cross-registry versions |
| [universal-reference-contracts.md](../reference/universal-reference-contracts.md) | Stable IDs |
| [dependency-graph.md](../reference/dependency-graph.md) | Requires / optional / conflicts / … |
| [business-bundle-contracts.md](../reference/business-bundle-contracts.md) | Bundles |
| [pricing-catalog.md](../reference/pricing-catalog.md) | Pricing |
| [subscription-contracts.md](../reference/subscription-contracts.md) | Subscriptions |
| [license-entitlement-contracts.md](../reference/license-entitlement-contracts.md) | License / entitlement |
| [activation-flow-contracts.md](../reference/activation-flow-contracts.md) | Activation events |
| [commercial-compatibility-matrix.md](../reference/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.