# 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-020.md), [ADR-021](ADR-021.md), [ADR-003](ADR-003.md), [ADR-008](ADR-008.md) |

## 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](ADR-021.md)). 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](ADR-021.md), 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

- [Commercial Platform Architecture](../commercial-platform-architecture.md)
- [Business Bundle Contracts](../../reference/business-bundle-contracts.md)
- [Business Bundles Catalog](../../reference/business-bundles.md)
- [Pricing Catalog](../../reference/pricing-catalog.md)
- [Subscription Contracts](../../reference/subscription-contracts.md)
- [License & Entitlement Contracts](../../reference/license-entitlement-contracts.md)
- [Business Type Catalog](../../reference/business-type-catalog.md)
- [Recommendation Contracts](../../reference/recommendation-contracts.md)
- [Activation Flow Contracts](../../reference/activation-flow-contracts.md)
- [Commercial Admin Portal Spec](../../reference/commercial-admin-portal-spec.md)
- [Payment Contracts](../../reference/payment-contracts.md) · [ADR-020](ADR-020.md) · [ADR-021](ADR-021.md) · [ADR-022](ADR-022.md)

---

## 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)

12. 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.
13. Introduce **Marketplace Compatibility** declarations on products (`requires_marketplace`, `marketplace_optional`, `marketplace_compatible`, publisher/consumer/plugin/extension/integration roles). Marketplace remains an independent product.
14. Introduce an **Automation Catalog** (types + packs). **Automation is not a PlatformProduct.**
15. 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.
16. Introduce a **Capability Registry**. Capabilities are independent reusable objects; products consume them; bundles reference them; definitions are never duplicated.
17. **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.
18. **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**.
19. Introduce a **Commercial Dependency Graph** (`requires`, `optional`, `conflicts`, `recommended`, `deprecated`, `replacement`).
20. This amendment remains **architecture + contracts only**. It does not authorize backend/frontend/DB/API implementation or any future product engines.

### Related Documents (v1.1)

- [Product Catalog](../../reference/product-catalog.md)
- [Product Registry](../../reference/product-registry.md)
- [Capability Registry](../../reference/capability-registry.md)
- [Automation Catalog](../../reference/automation-catalog.md)
- [Extension Registry](../../reference/extension-registry.md)
- [Dependency Graph](../../reference/dependency-graph.md)
- [Commercial Compatibility Matrix](../../reference/commercial-compatibility-matrix.md)
- [Commercial Foundation v1.1 Report](../../commercial-platform-foundation-v1.1-report.md)

---

## 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)

21. 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.
22. Document **Asset Lifecycle** states: draft, review, published, deprecated, archived, deleted, versioned, cloned, installed, shared, marketplace_ready (plus install/share records).
23. 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.
24. 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.
25. Policies may target open kinds: product, bundle, capability, subscription, license, tenant, workspace, business type, country, region, industry, automation, asset, metadata, and future object types.
26. Document **Asset Marketplace** distribution modes (installed, shared, cloned, purchased, free, enterprise only, private, organization only, marketplace ready) without implementing Marketplace.
27. **All registries support versions** via shared versioning contracts.
28. **Every registry object** receives a stable universal `registry_object_id` — commercial cross-refs must not use service-specific identifiers as SoT.
29. 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)

- [Asset Registry](../../reference/asset-registry.md)
- [Asset Lifecycle](../../reference/asset-lifecycle.md)
- [Asset Marketplace Contracts](../../reference/asset-marketplace-contracts.md)
- [Metadata Registry](../../reference/metadata-registry.md)
- [Policy Engine Contracts](../../reference/policy-engine-contracts.md)
- [Policy Targets](../../reference/policy-targets.md)
- [Registry Versioning](../../reference/registry-versioning.md)
- [Universal Reference Contracts](../../reference/universal-reference-contracts.md)
- [Commercial Foundation v1.2 Report](../../commercial-platform-foundation-v1.2-report.md)