Integration

1. Sister Services

Direction: → calls / ← called by / ↔ bidir. The build-time dependency is @nx/core only; all coupling below is via shared DB or Kafka CDC.

Sister	Direction	Surface	Contract	Auth	Failure Mode	Idempotency
@nx/commerce	←	Kafka public.Product (Debezium)	CDC envelope (TProductPgRow)	—	at-least-once; log + skip	(productId, taxGroupId, op)
@nx/pricing	←	Shared DB read pricing.TaxSet / pricing.Tax	Drizzle row shape	—	n/a (read)	n/a
@nx/invoice	←	TaxInfo consumer (no taxation surface)	coupled via core models only	—	n/a	n/a
@nx/identity	←	JWT issuer; JWKS verified per request	ES256 JWKS	JWT	request fails 401	n/a
commerce MerchantRepository	→	In-process DI (MerchantRepository) for taxMethod lookup	repository contract	—	throws on not-found	n/a

TaxGroupService injects a MerchantRepository-like binding to read merchant taxMethod during validation. The binding is resolved from the shared DI graph, not via HTTP.

2. External Systems

System	Direction	Surface	Auth	Failure Mode
Kafka / Debezium	←	Consume public.Product	SASL SCRAM-SHA-512	broker reconnect (logged)
PostgreSQL	↔	tax + pricing schemas	user/pass	pool error

3. Critical Cross-Service Flows

3.1 Product change → tax provisioning

Step	Detail
1-2	Commerce owns Product; Debezium captures the row change
3-4	Taxation reconciles: provision when taxGroupId set, else deprovision
5	Pricing reads the provisioned TaxSet/Tax directly — no event from taxation

3.2 Merchant tax-method validation

Step	Detail
4	DIRECT merchant cannot use a DEDUCTION group (and vice versa); unset merchant taxMethod allows any

4. Contract Stability

Surface	Stability	Versioning
HTTP /tax-groups, /tax-group-items	stable	URL /v1/
HTTP /tax-provisioning/*	stable	URL /v1/
HTTP /vn-* reads	stable	URL /v1/
Kafka public.Product (inbound)	external (Debezium-defined)	Debezium schema
pricing.TaxSet / pricing.Tax shared read	stable (core-owned)	schema migration

5. Related Pages

• API Events
• Pricing
• Commerce
• Decisions