Integration

@nx/search integrates by being embedded, not called over the network. The host registers its components and uses SearchService + SearchableControllerMixin in-process.

1. Sister Services

Sister	Direction	Surface	Contract	Auth	Failure Mode
commerce (host)	←	In-process — registers 4 components, calls SearchService, applies SearchableControllerMixin	Library API	Inherited (host JWT/Basic)	In-process exception
@nx/core	→	ConfigurationRepository, CdcTables, EnvironmentKeys, SystemConfigurations	Library	—	Compile-time dependency

Commerce applies the mixin to its organizer / merchant / category / device / sale-channel / product / product-variant controllers, each overriding resolveSearchScope() to inject a merchant/tenant where scope.

2. External Systems

System	Direction	Surface	Auth	Failure Mode
Typesense	→	HTTP (typesense client) — search, import, collection CRUD, health	API key (APP_ENV_TYPESENSE_API_KEY)	Health probe → circuit breaker pauses CDC; search errors classified + retried
Kafka + Debezium	←	Consume CDC topics (@platformatic/kafka, Avro via avsc)	SASL optional (APP_ENV_KAFKA_SASL_*)	DLQ for poison messages; offsets uncommitted on failure

3. Critical Cross-Service Flows

3.1 Consumer wires per-entity search (build-time)

Step	Detail
2	Nodes parsed from protocol:host:port CSV; default http:localhost:8108
6	embed.from wired only when DB embedding config + collection embeddingField/embeddingFields present
7	Missing collections created; diverged ones logged (manual migration)

3.2 Tenant-scoped search at request time

Step	Detail
2	Host override returns a where object; mixin and-merges it with the caller filter
3	Empty scope (null) means open search (no tenant restriction)

4. Contract Stability

Surface	Stability	Versioning
Component registration order	stable	Library semver (@nx/search)
SearchableControllerMixin(Base, options)	stable	Library semver
ISearchParams / ISearchResponse	stable	Library types
GET /search/{collectionName} (generic controller)	stable	Host URL /v1/
CDC topic names (nx.seller.{schema}.{table})	coupled to Debezium connector config	Connector-owned
Typesense collection schemas	evolving (additive via backfill scripts)	Manual migration on divergence

5. Related Pages

• API Events
• Configuration
• Decisions
• Commerce — host service