78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
# Commercial Dependency Graph
|
|
|
|
> **Architecture / contracts only.**
|
|
> Contract version: `commercial-dependency.v1`
|
|
> Used by: Products, Capabilities, Bundles, Automation Packs, Extensions
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
A unified **dependency graph** expresses relationships between commercial entities without embedding implementations.
|
|
|
|
---
|
|
|
|
## 2. Node kinds
|
|
|
|
| `node_kind` | Code space |
|
|
| --- | --- |
|
|
| `product` | `product_code` |
|
|
| `capability` | `capability_code` |
|
|
| `bundle` | `bundle_code` |
|
|
| `automation_pack` | `automation_pack_code` |
|
|
| `extension` | `extension_code` |
|
|
| `pricing_item` | `pricing_item_code` |
|
|
| `service` | `service_identifier` |
|
|
|
|
---
|
|
|
|
## 3. Edge — CommercialDependency
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `from_kind` / `from_code` | | Subject |
|
|
| `to_kind` / `to_code` | | Object |
|
|
| `relation` | DependencyRelation | See §4 |
|
|
| `strength` | enum? | `hard` \| `soft` |
|
|
| `reason` | string? | |
|
|
| `effective_from` / `effective_to` | datetime? | |
|
|
|
|
---
|
|
|
|
## 4. DependencyRelation
|
|
|
|
| Relation | Meaning |
|
|
| --- | --- |
|
|
| `requires` | Subject cannot activate without object |
|
|
| `optional` | Object may enhance subject |
|
|
| `conflicts` | Subject and object must not both be active |
|
|
| `recommended` | Soft suggestion (recommendations / UX) |
|
|
| `deprecated` | Subject should not be used; see replacement |
|
|
| `replacement` | Object replaces subject |
|
|
|
|
---
|
|
|
|
## 5. Illustrative dependency matrix (examples)
|
|
|
|
| From | Relation | To | Notes |
|
|
| --- | --- | --- | --- |
|
|
| `product.pay` | requires | capability `payments` | |
|
|
| `product.driver` | optional | capability `maps` | |
|
|
| `product.qr` | recommended | capability `short-links` | Future |
|
|
| `product.marketplace` | conflicts | *(none fixed)* | Independent |
|
|
| `bundle.restaurant.starter` | requires | `product.pay` | Via product ref |
|
|
| `bundle.restaurant.starter` | recommended | automation_pack `pack.order_sms` | Example |
|
|
| `product.short_link` | replacement | *(legacy link module if any)* | Future |
|
|
| `ext.pay.checkout_widget` | requires | `product.pay` | |
|
|
| `product.booking` | requires | capability `appointments` | Reserved |
|
|
|
|
---
|
|
|
|
## 6. Graph invariants
|
|
|
|
1. No cycles on `requires` edges (logical validation rule for future engines).
|
|
2. `conflicts` is symmetric when materialized.
|
|
3. `replacement` implies subject `deprecated` (recommended pairing).
|
|
4. Graph stores **references only** — no workflow or pricing amounts.
|
|
5. Unlimited nodes/edges via registry — architecture unchanged.
|