168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# 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)
|
||
|