Search

@nx/search là một package dạng thư viện, không phải ứng dụng IGNIS độc lập. Nó ship bốn IGNIS component mà một host service (hiện là commerce) đăng ký, cộng với một SearchableControllerMixin mà consumer nối lên các REST controller của riêng họ. Nó giữ ~8 Typesense collection đồng bộ với PostgreSQL qua một pipeline CDC Debezium → Kafka và phục vụ tìm kiếm keyword + ngữ nghĩa tùy chọn.

1. Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/search
Code	LIB-SEARCH
Loại	Thư viện / component package (tiêu thụ bởi commerce)
Runtime	Bun (>=1.3.8) — chạy bên trong process host
Base Class	N/A — không có lớp Application; export các lớp con BaseComponent
Vị trí	packages/search
Base Path	/search (mount dưới base path của host service)
Dev Port	N/A — package thư viện, không có port riêng
Container Port	N/A — chạy trong container host (commerce)
Snowflake ID	N/A — host service sở hữu cấp phát ID
Search Engine	Typesense ^3.0.3 (nodes dạng protocol:host:port)
Sync Source	Debezium → Kafka CDC (schema public, pricing, inventory)
Consumed by	commerce
Binding Namespace	@nx/search

Bản chất thư viện: không có application.ts, index.ts → bootstrapApplication(), port riêng, hay DB schema riêng. Ứng dụng host đăng ký bốn component theo thứ tự dependency; tất cả collection, service, CDC consumer, và SearchController generic được nối vào IGNIS container của host. Xem ADR-0001.

2. Mục đích & Phạm vi

Bao gồm	Không bao gồm
Tìm kiếm full-text keyword trên 8 Typesense collection	Sở hữu các bảng nguồn (commerce/pricing/inventory sở hữu chúng)
Tìm kiếm ngữ nghĩa / hybrid tùy chọn qua auto-embedding	Hosting model embedding (config Typesense/Google bên ngoài)
CDC consumer: Debezium → Kafka → Typesense sync	Bản thân Debezium connector (do infra sở hữu)
Cascade fan-out từ bảng join/related tới doc principal	Write API để mutate document trực tiếp từ client
Dịch where/order/fields/include kiểu Ignis → Typesense	Pattern operator (like/ilike/regexp) — dùng text search
SearchableControllerMixin cho /search + /search/count theo từng entity	Tenant scope policy (host override resolveSearchScope)
Phát hiện schema drift (migration thủ công khi phân kỳ)	Auto-rebuild collection đã phân kỳ (thủ công, tránh mất dữ liệu)

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, BaseComponent, BaseRestController, DI
@venizia/ignis-helpers	Logger, applicationEnvironment, HTTP helpers
typesense	Typesense client — collection CRUD, search, import
@platformatic/kafka	CDC Kafka consumer + DLQ producer
avsc	Giải mã Avro các payload CDC Debezium
@hono/zod-openapi	Schema Zod request/response cho route search
zod	Validate schema
lodash	Tiện ích

Nội bộ:

Package	Mục đích
@nx/core	CdcTables, ConfigurationRepository, EnvironmentKeys, SystemConfigurations, base class, DI

4. Cấu trúc Project

packages/search/
├── src/
│   ├── index.ts                    # Barrel — re-export components, services, helpers
│   ├── component.ts                # ApplicationSearchComponent
│   ├── components/
│   │   ├── embedding-configuration.component.ts
│   │   ├── typesense-search-engine.component.ts
│   │   └── cdc.component.ts
│   ├── common/                     # keys, environments, constants, kafka-topics,
│   │                               # search.types, relations, pipeline-config types
│   ├── configurations/             # 8 collection configs + schema-fragments.ts
│   ├── controllers/                # SearchController + searchable.mixin + definitions
│   ├── datasources/                # (re-export)
│   ├── helpers/                    # typesense, converter, registry, include, migration
│   ├── mappers/                    # DB row → Typesense doc (theo từng entity + *-info)
│   ├── services/
│   │   ├── search/                 # SearchService, SearchIndexingService
│   │   ├── cdc/                    # kafka, cdc, cascade, enrichment, circuit-breaker
│   │   └── search-configuration.service.ts
│   ├── migrations/processes/       # backfill processes
│   └── utilities/                  # error-classifier, with-retry, errors
├── scripts/                        # data-feeder, migrate-add-*, check_sync_status.sh
└── package.json

Không có application.ts / migrate.ts / models/ / repositories riêng — đây là thư viện, không phải service.

5. Architecture

@nx/search chạy bên trong host service (commerce). Sơ đồ thể hiện nó được nhúng.

Chi tiết: xem Architecture.

6. Snapshot Domain

Không có schema PostgreSQL riêng — "domain" là tập các Typesense collection, mỗi cái là một projection denormalized của các bảng nguồn.

Schema collection đầy đủ + cascade source: xem Domain Model.

7. Tổng quan bề mặt

REST controllers — @nx/search expose hai endpoint; phần lớn consumer dùng mixin thay vì controller generic. Schema đầy đủ render trực tiếp từ /doc/openapi.json của host service (commerce), không phải từ thư viện này.

Nguồn	Base path	Endpoints
SearchController (generic)	/search/{collectionName}	2 (GET, GET …/count)
SearchableControllerMixin (theo từng entity, trên controller consumer)	<entity>/search	2 mỗi controller

Permission	Action
search:search	Tìm kiếm document
search:search-count	Đếm document khớp

Async topics (tham chiếu đầy đủ trong API Events):

Hướng	Số lượng
Inbound (Kafka CDC)	18 topic trên 3 schema
Outbound (Kafka)	1 — DLQ (nx.seller.cdc.dlq)
WebSocket out	0
BullMQ jobs in/out	0

8. Components

Đăng ký bởi host theo thứ tự này:

Thứ tự	Component	File	Mục đích
1	ApplicationSearchComponent	src/component.ts	Parse Typesense nodes + 8 collection config từ env, bind SEARCH_COMPONENT_OPTIONS, đăng ký ConfigurationRepository + SearchConfigurationService
2	ApplicationEmbeddingConfigurationComponent	src/components/embedding-configuration.component.ts	Load config model embedding tùy chọn + config pipeline từ DB; bind EMBEDDING_MODEL_CONFIG + SEARCH_PIPELINE_CONFIG
3	TypesenseSearchEngineComponent	src/components/typesense-search-engine.component.ts	Build TypesenseHelper, đăng ký collection vào CollectionRegistry (nối embed.from), đăng ký service + SearchController, chạy schema-drift check
4	ApplicationCdcComponent	src/components/cdc.component.ts	Khởi động CDCKafkaService trên ALL_CDC_TOPICS, với DLQ + circuit breaker tùy chọn

9. Services

Service	File	Mô tả ngắn
SearchService	src/services/search/search.service.ts	Phía query: filter Ignis → Typesense, resolve include, trả về { count, data }
SearchIndexingService	src/services/search/search-indexing.service.ts	Phía write: upsert/delete single + batch, metric throughput, getHealth()
CDCService	src/services/cdc/cdc.service.ts	handleBatch() — route các dòng CDC tới mapper, upsert/delete
CDCCascadeService	src/services/cdc/cdc-cascade.service.ts	Fan-out thay đổi bảng join/related để tính lại doc principal
CDCEnrichmentService	src/services/cdc/cdc-enrichment.service.ts	Hydrate doc với dữ liệu cross-collection
CDCCircuitBreakerService	src/services/cdc/cdc-circuit-breaker.service.ts	Probe Typesense health, pause consume khi down (opt-in)
CDCKafkaService	src/services/cdc/cdc-kafka.service.ts	Kafka consumer, batching, route DLQ
SearchConfigurationService	src/services/search-configuration.service.ts	Đọc config embedding + pipeline từ bảng Configuration

10. Repositories

Repository	Bảng	Nguồn	Method tùy chỉnh
ConfigurationRepository	core.Configuration	@nx/core	— (đăng ký, không sở hữu; đọc config embedding/pipeline)

Search không sở hữu bảng nào; nó không có repository riêng.

11. Entry Points

File	Mục đích
src/index.ts	Barrel export — host import component từ đây
src/component.ts	ApplicationSearchComponent (entry component)
scripts/migrate-add-references.ts	Backfill trường relation/reference trong Typesense (migrate:references)
scripts/migrate-add-denorm-fields.ts	Backfill trường denormalized (migrate:denorm)
scripts/data-feeder/index.ts	Feed dữ liệu giả qua Commerce API (feed-data)

Không có bootstrapApplication() / bootstrapMigration() — những cái đó thuộc về host service.

12. Configuration

Typesense nodes/API key, env CDC + circuit-breaker, config embedding + pipeline lưu trong DB: xem Configuration.

13. Operations

Chạy bên trong commerce — không deploy độc lập. Schema migration, CDC lag, chẩn đoán sync: xem Operations.

14. Trang liên quan

• Architecture
• Domain Model
• API Events
• Integration
• Configuration
• Operations
• Semantic Search Selection — đánh giá vector DB + model embedding
• Decisions
• REST endpoints — OpenAPI trực tiếp tại host service /v1/api/commerce/doc/openapi.json
• Commerce — host / consumer chính