Operations

@nx/search has no independent deployment. It runs inside the host (commerce) container and shares its lifecycle, replicas, and resources. Operating it means operating Typesense, the Debezium connector, and the CDC consumer running in commerce.

1. Deployment

Property	Value
Image	N/A - packaged into the commerce image
Replicas	N/A - equals commerce replicas
Resources	Adds Kafka consumer + Typesense client memory to the host
Probes	Host probes; TypesenseHelper.getHealth() gates collection sync + circuit breaker
Migration mode	On-boot schema-drift check (no auto-apply); manual backfill scripts for changes
Snowflake ID range	N/A

Dependencies that must be reachable

Dependency	Required for	If down
Typesense	search + indexing	Bootstrap skips collection sync (logs warn); circuit breaker pauses CDC
Kafka + Debezium	CDC sync	Index stops updating; consumer reconnects; offsets uncommitted

No Traefik labels - the routes mount under the host service's base path (/v1/api/commerce/...).

2. Observability

Signal	Source	Where to look
Logs	Host stdout (structured key-value)	commerce pod logs - filter component scopes (ApplicationCdcComponent, TypesenseSearchEngineComponent)
CDC startup	log line Starting CDC consumer | Brokers… | DLQ… | CircuitBreaker…	confirms topics + breaker state
Schema sync	log Schema divergence detected | Collection: …	indicates manual migration needed
Indexing throughput	SearchIndexingService batch metrics	log fields per batch
Health	TypesenseHelper.getHealth()	breaker probe + bootstrap gate

Sync diagnostic

Operation	Command
Check Typesense ↔ source row counts	Compare Postgres row counts against the Typesense collection's num_documents
Dry-run add-only schema migration	bun run migrate
Dry-run blue-green collection rebuild	bun run migrate:rebuild

3. Security

Concern	Mitigation
AuthN	Search routes inherit host JWT/Basic (AuthenticateStrategy.JWT, .BASIC)
AuthZ	search:search / search:search-count; mixin requires consumer authorize config
Tenant isolation	resolveSearchScope() and-merges a where scope into every query
Typesense API key	APP_ENV_TYPESENSE_API_KEY from host secrets; never in code
Kafka SASL	APP_ENV_KAFKA_SASL_* when broker requires auth
No client writes	Documents mutated only via CDC - no public write API

4. Runbook

4.1 Alert classes

Alert	Trigger	Check	Fix	Escalate
searchSchemaDivergence	log Schema divergence detected on boot	Compare config vs live Typesense schema	Run backfill script for additive change; recreate collection only if data-loss-safe	backend on-call
searchCdcLag	CDC consumer falling behind / circuit OPEN	Typesense health, Kafka consumer-group lag	Recover Typesense; breaker closes after quiet window	SRE on-call
searchDlqGrowth	messages accumulating in nx.seller.cdc.dlq	Inspect DLQ payloads + failure metadata	Fix mapper/data, replay from DLQ	backend on-call
searchStale	results missing recently-changed rows	Compare Postgres row counts vs Typesense num_documents	Backfill or replay affected topics	backend on-call

4.2 Common operations

Operation	Command / Action
Tail CDC logs	kubectl logs -f deploy/commerce | grep -E 'Cdc|Typesense'
Verify sync counts	Compare Postgres row counts vs the Typesense collection's num_documents
Apply add-only schema changes	bun run migrate:apply (diff + PATCH onto live collections)
Rebuild a collection (breaking change)	bun run migrate:rebuild:apply (blue-green copy + atomic alias swap)
Backfill existing DB rows into CDC	bun run backfill:apply (Debezium incremental-snapshot signal)
Reindex after schema change	Recreate the diverged collection (data-loss-safe window) then backfill
Replay a CDC topic	Reset the Debezium connector / consumer-group offsets (infra-owned)

5. Related Pages

• Configuration
• /runbook/ - central runbook for cross-service incidents
• Decisions