Integration

1. Sister Services

Sister	Direction	Surface	Auth	Failure Mode	Idempotency
`@nx/identity`	`→`	HTTP JWKS (`/jw-certs`) for JWT verify	—	retry / boot fail	request-id
`@nx/search`	`↔`	Components (`ApplicationSearchComponent`, Typesense, Embedding); CDC consumer in WORKER role	—	CDC offset replay	per-PK upsert
`@nx/inventory`	`→` (CDC)	`public.Merchant`, `public.ProductVariant`	—	Debezium replay	per-PK; seeds location + `InventoryItem`
`@nx/pricing`	`→` (CDC)	`pricing.Fare*`, `public.ProductVariant`	—	Debezium replay	per-PK; fare init
`@nx/taxation`	`→` (CDC)	`public.Product` (taxGroupId)	—	Debezium replay	per-PK; tax provisioning
`@nx/invoice`	`→` (CDC)	`public.Merchant` → `TaxInfo`	—	Debezium replay	per-PK; `TaxInfo` authoritative
`@nx/asset`	`↔`	`ApplicationAssetComponent` (Minio); MetaLinks	—	upload retry	by asset id
`@nx/sale`	`←`	HTTP read of `ProductVariant`, `ProductInfo`, `SaleChannel`, `Category`	JWT (s2s)	retry	snapshot on order

Commerce does not push to inventory/pricing/taxation/invoice directly — all four consume CDC. See ADR-0002.

System	Via	Notes
Minio	`@nx/asset`	Object storage for product/variant media
Typesense	`@nx/search`	Search engine; populated by CDC, not by commerce directly
Kafka / Debezium	infra	Commerce only writes Postgres; Debezium (Kafka Connect) does the WAL capture
Payment/e-invoice providers	encrypted `Configuration`	Commerce stores credentials (AES-256-GCM); actual calls owned by payment/invoice services

No direct third-party API calls from commerce source — provider credentials are captured here and consumed elsewhere.

COMBO variants are not in STOCKABLE_SET, so inventory seeds no InventoryItem for them.

Surface	Stability	Versioning
HTTP `/v1/api/commerce/*`	stable	URL prefix `/v1/`
CDC topics (`public.*`)	schema-coupled	additive columns safe; renames break consumers — coordinate
`Merchant.metadata.tax` shape	stable	additive fields only (`taxCode` required)
EventBus event keys	internal	not a public contract
BullMQ job shape	internal	not a public contract