# Platform Product Catalog

> **Architecture / contracts only.** Open-ended product model — never a closed enum.  
> ADR: [ADR-023](../architecture/adr/ADR-023.md) (v1.1 amendment)  
> Contract version: `platform-product.v1`  
> Registry: [product-registry.md](product-registry.md)

---

## 1. Purpose

Every commercial offering in the TorbatYar ecosystem is a **PlatformProduct**.

Products are **installable registry entries**. Adding a product MUST NOT require changing Core commercial architecture — only registry + documentation (+ optional bundle mapping).

**Automation is not a PlatformProduct** — see [automation-catalog.md](automation-catalog.md).

---

## 2. Aggregates

### 2.1 PlatformProduct

| Field | Type | Meaning |
| --- | --- | --- |
| `product_code` | string | Stable unique code (open registry) |
| `display_name` | string | Human label |
| `category_code` | string | Ref → PlatformProductCategory |
| `default_version` | string | Current `version_code` |
| `commercial_status` | enum | `planned` \| `preview` \| `ga` \| `deprecated` \| `retired` |
| `maturity` | enum | `concept` \| `alpha` \| `beta` \| `stable` \| `mature` |
| `visibility` | PlatformProductVisibility | |
| `lifecycle` | PlatformProductLifecycle | |
| `metadata` | PlatformProductMetadata | |
| `tags` | PlatformProductTags | |
| `owner_service_identifier` | string? | Owning runtime service when materialized |
| `documentation_ref` | string | Path/URL to docs |
| `ext` | object | Additive reserved |

### 2.2 PlatformProductCategory

| Field | Type | Meaning |
| --- | --- | --- |
| `category_code` | string | Open string (e.g. `platform`, `vertical`, `channel`, `future`) |
| `display_name` | string | |
| `parent_category_code` | string? | Optional hierarchy |
| `sort_order` | int | |

Categories are **open**. Examples (non-exhaustive, not hardcoded limits): `platform`, `commerce`, `operations`, `engagement`, `vertical`, `content`, `infrastructure`, `ai`, `future`.

### 2.3 PlatformProductCapability

| Field | Type | Meaning |
| --- | --- | --- |
| `product_code` | string | |
| `capability_code` | string | Ref → Capability Registry — **never inline-define** |
| `role` | enum | `provides` \| `consumes` \| `requires` |
| `required` | bool | |

### 2.4 PlatformProductDependency

| Field | Type | Meaning |
| --- | --- | --- |
| `product_code` | string | Subject |
| `depends_on_kind` | enum | `product` \| `capability` \| `service` \| `extension` \| `automation_pack` |
| `depends_on_code` | string | Target code |
| `relation` | enum | See [dependency-graph.md](dependency-graph.md): `requires` \| `optional` \| `conflicts` \| `recommended` \| `deprecated` \| `replacement` |
| `notes` | string? | |

### 2.5 PlatformProductVisibility

| Field | Type | Meaning |
| --- | --- | --- |
| `public_catalog` | bool | |
| `admin_only` | bool | |
| `partner_only` | bool | |
| `hidden` | bool | |
| `regions[]` | string[] | Future |
| `tenant_tiers[]` | string[] | Soft gate |

### 2.6 PlatformProductLifecycle

| Field | Type | Meaning |
| --- | --- | --- |
| `sellable` | bool | May appear in commercial offers |
| `installable` | bool | May be activated for a tenant |
| `grandfathered` | bool | |
| `replacement_product_code` | string? | |
| `sunset_at` | datetime? | |

### 2.7 PlatformProductMetadata

| Field | Type | Meaning |
| --- | --- | --- |
| `locale_labels` | map | i18n |
| `icon_key` | string? | |
| `sort_order` | int | |
| `marketing_blurb` | string? | Non-normative |
| `ext` | object | |

### 2.8 PlatformProductVersion

| Field | Type | Meaning |
| --- | --- | --- |
| `product_code` | string | |
| `version_code` | string | Commercial/product version |
| `changelog` | string | |
| `capability_bindings[]` | PlatformProductCapability | |
| `dependencies[]` | PlatformProductDependency | |
| `required_services[]` | string[] | Service identifiers |
| `optional_services[]` | string[] | |
| `reserved_features[]` | string[] | Feature keys reserved / not yet implemented |
| `compatibility` | PlatformProductCompatibility | |
| `marketplace` | MarketplaceCompatibilityDeclaration | See marketplace section / [product-registry.md](product-registry.md) |
| `extension_pubs[]` | string[] | Extension codes published by this version |
| `automation_pack_refs[]` | string[] | Automation pack refs (not products) |
| `effective_from` / `effective_to` | datetime? | |

### 2.9 PlatformProductCompatibility

| Field | Type | Meaning |
| --- | --- | --- |
| `min_platform_commercial_version` | string | e.g. `commercial.v1.1` |
| `compatible_product_codes[]` | string[] | Soft list |
| `incompatible_product_codes[]` | string[] | |
| `published_resource_compatible` | bool | Aligns with ADR-022 when true |
| `payment_l1_required` | bool | Needs Core payment entitlement |
| `notes` | string? | |

### 2.10 PlatformProductTags

| Field | Type | Meaning |
| --- | --- | --- |
| `tags[]` | string[] | Open tag registry |

---

## 3. Illustrative product matrix (examples — NOT a closed set)

| product_code (example) | Display name | Category (example) | Maturity |
| --- | --- | --- | --- |
| `product.crm` | Torbat CRM | platform | stable |
| `product.pay` | Torbat Pay | commerce | stable |
| `product.pages` | Torbat Pages | content | stable |
| `product.driver` | Torbat Driver | operations | stable |
| `product.restaurant` | Restaurant | vertical | stable |
| `product.healthcare` | Healthcare | vertical | beta |
| `product.beauty` | Beauty | vertical | beta |
| `product.accounting` | Accounting | platform | stable |
| `product.communication` | Communication | engagement | stable |
| `product.loyalty` | Loyalty | engagement | stable |
| `product.marketplace` | Marketplace | commerce | concept |
| `product.qr` | QR | channel | concept |
| `product.short_link` | Short Link | channel | concept |
| `product.business_card` | Business Card | channel | concept |
| `product.booking` | Booking | operations | concept |
| `product.ticketing` | Ticketing | operations | concept |
| `product.events` | Events | engagement | concept |
| `product.learning` | Learning | content | concept |
| `product.automation` | *(forbidden as product — use Automation Catalog)* | — | — |
| `product.storage` | Storage | infrastructure | concept |
| `product.ai.*` | Future AI Products | ai | concept |

**Rule:** Any future `product.*` code may be registered without amending this architecture document’s structure.

---

## 4. Invariants

1. Product codes are an **open string registry** — architecture MUST NOT hardcode a closed product list.
2. Products **consume** capabilities from the Capability Registry; they do not redefine them.
3. Marketplace remains an independent product; others declare marketplace compatibility only.
4. Automation packs are referenced, never classified as PlatformProducts.
5. Implementation of a product requires a future registered phase — registration alone does not ship engines.