# Meilisearch — Volltextsuche als First-Class-Capability **Status:** completed **Task-ID:** #48 **Phase:** 04 **Estimated Effort:** 1 Woche **Owner:** unassigned ## Problem Aktuell liefert die Boilerplate Suchfunktionalität ausschließlich über `WHERE ... LIKE '%foo%'`-Patterns gegen Postgres (z.B. KB-Article-Public-Search, CRM-Contacts-Filter, Row-Search in Entities). Das hat mehrere Schmerzpunkte: - **Keine Relevanz-Ranking** — Ergebnisse sind in Insert-Order, nicht nach Match-Quality. - **Keine Typo-Tolerance** — Tippfehler in der Query produzieren leere Ergebnislisten. - **Volle Tabellen-Scans** — auch mit B-Tree-Indexen sind `LIKE '%x%'`-Queries nicht index-served; bei Tenants mit >50k Rows merkt man das. - **Kein Highlighting, kein Facetting** — UI-Features wie "Filter-Pills + Snippet-Markierung" lassen sich nicht ohne Aufwand bauen. - **Schreib- und Lesepfad gekoppelt** — jede Search-Query lastet den Primary-Postgres aus. Wir brauchen eine dedizierte Search-Engine die als async-indexed Read-Side neben Postgres läuft. Meilisearch ist die richtige Wahl (vs Elasticsearch / Typesense): kompakt, schnell genug für unsere Größenklasse, einfaches Tenant-Filter-Pattern, gute Default-Tuning-Werte, MIT-lizenziert und selbsthostbar. ## Depends on - `03-scaling-infrastructure/outbox-pattern.md` (#42) — die Indexer-Worker konsumieren Outbox-Events, niemals direkte Domain-Hooks. Ohne Outbox riskieren wir Dual-Write-Inkonsistenzen zwischen Postgres und Meilisearch. - `03-scaling-infrastructure/worker-queues.md` (#43) — der Indexer läuft als BullMQ-Job im `worker-general`-Service. Voraussetzung: Worker-Queue-Infrastruktur steht. ## Blocks - `04-search-rag/embedding-pipeline.md` (#50) — Pattern der Indexer-Worker (Outbox-Konsument, Tenant-Scope, Bulk-Reindex-Command) wird hier etabliert und vom RAG-Indexer kopiert. - `07-chatbot/chatbot-v2.md` — Chatbot V2 nutzt Meilisearch für strukturierte Filter-Searches in Knowledge-Base-Treffern (komplementär zur semantischen Suche). - diverse UI-Verbesserungen in `apps/web` (Faceted-Filter-UI, Search-Highlights) sind erst nach diesem Task implementierbar. ## Approach **Meilisearch als externe Search-Engine, angesprochen über ein neues Package `packages/search/` als Wrapper.** Indexing erfolgt ausschließlich async über Outbox-Events; das Domain-Model bleibt Source-of-Truth und Meilisearch ist eine projizierte Read-Side. Tenant-Isolation wird auf zwei Ebenen erzwungen: jedes Document hat `tenantId` als `filterableAttribute`, und der Wrapper verbietet Raw-Queries — jede Search muss durch `searchInIndex({ index, tenantId, query, ... })` mit explizitem Tenant gehen, der intern in den Meilisearch-Filter `tenantId = ""` umgewandelt wird. **Alternativen verworfen:** - **Postgres-FTS (tsvector / pg_trgm)**: keine Relevanz-Tuning-Knobs auf dem Niveau, keine eingebaute Typo-Tolerance, koppelt Read- an Schreibpfad-Postgres. - **Elasticsearch / OpenSearch**: Overkill für unsere Größenordnung; Memory-Hunger und Ops-Aufwand zu hoch. - **Typesense**: vergleichbar, aber Meilisearch hat mature Multi-Tenancy via Filter, bessere Doku, und ein bereits in Coolify gepflegtes Image. - **Algolia (SaaS)**: cost-prohibitive bei Multi-Tenant-Skalierung; außerdem unvereinbar mit DSGVO-Selfhost-Anforderungen. **Fallback-Strategie:** Wenn Meilisearch nicht erreichbar (Container down, Network-Error), fallen die bestehenden Hot-Paths transparent auf die alte SQL-LIKE-Variante zurück. Wrapper-Helper `searchWithFallback({ index, fallbackQuery })` kapselt das Pattern. Suche bleibt degradiert verfügbar — keine 500er. ## Implementation Steps 1. **Meilisearch-Container in docker-compose.yml ergänzen** — neuer Service `meilisearch` mit Image `getmeili/meilisearch:v1.8`, Volume für persistenten Index, Health-Check, ENV-Vars `MEILI_MASTER_KEY` und `MEILI_ENV=development` (lokal) bzw. `MEILI_ENV=production` (staging/prod). - Files: `docker-compose.yml`, `docker-compose.dev.yml` (falls separat), `.env.example` mit `MEILI_URL=http://localhost:7700`, `MEILI_MASTER_KEY=devkey` - Commit: `04/meilisearch: add meilisearch service to docker-compose` 2. **Production-Deploy-Variante dokumentieren** — Snippet für Hetzner-Coolify-Stack mit Volume-Backup-Cron + Snippet für Scaleway-Managed-Instance- oder Fly-VM-Deploy. Inkl. Master-Key-Rotation-Anleitung. - Files: `docs/deploy/meilisearch.md` (neu) - Commit: `04/meilisearch: document production deployment options` 3. **Package `packages/search/` initialisieren** — TS-Package gemäß Repo-Convention (tsup, vitest, type-exports). Public-API: `createSearchClient({ url, apiKey })`, `createSearchIndex(...)`, `searchInIndex(...)`, `bulkIndex(...)`, `deleteFromIndex(...)`, `health()`. Typed Schema-Definitions in `packages/search/src/schemas/` mit einem File pro Index: `kb-articles.ts`, `crm-contacts.ts`, `rows.ts`, `entities.ts`, `users.ts`. - Files: `packages/search/package.json`, `packages/search/src/index.ts`, `packages/search/src/client.ts`, `packages/search/src/schemas/*.ts`, `packages/search/tsconfig.json`, `packages/search/vitest.config.ts` - Commit: `04/meilisearch: scaffold packages/search with typed client and schemas` 4. **Index-Helper `createSearchIndex` implementieren** — wrapper-Funktion die idempotent ein Meilisearch-Index anlegt oder updated. Signatur: ```ts createSearchIndex({ name: string, // z.B. "kb-articles" primaryKey: string, // z.B. "id" searchableAttributes: string[], // z.B. ["title", "content", "tags"] filterableAttributes: string[], // MUSS "tenantId" enthalten sortableAttributes: string[], // z.B. ["createdAt", "updatedAt"] rankingRules?: string[], // optional override stopWords?: string[], synonyms?: Record, }) ``` Helper validiert dass `tenantId` in `filterableAttributes` enthalten ist (throw bei Verstoß). - Files: `packages/search/src/index-helper.ts`, `packages/search/src/index-helper.test.ts` - Commit: `04/meilisearch: add createSearchIndex helper with tenant guard` 5. **Tenant-Scoped Query-Wrapper** — `searchInIndex({ index, tenantId, query, filters?, sort?, limit?, offset? })`. Intern wird der Filter immer mit `tenantId = "${tenantId}"` UND-verknüpft. Direkte Raw-Search-API ist im Package nicht exportiert. Zusätzlich: `searchWithFallback({ index, tenantId, query, fallbackQuery })` für graceful degradation. - Files: `packages/search/src/query.ts`, `packages/search/src/query.test.ts` - Commit: `04/meilisearch: enforce tenant-scope on every search query` 6. **Indexer-Worker im worker-general registrieren** — neuer BullMQ-Job-Handler `search.index`, `search.delete`, `search.bulk-reindex`. Konsumiert Outbox-Events vom Job-Producer (siehe `outbox-pattern.md`). Event-Payload: `{ tenantId, indexName, documentId, document? }`. Bei `search.index` → upsert; bei `search.delete` → delete-by-primaryKey; bei `search.bulk-reindex` → iteriert per Cursor über Postgres, batched 1000-er-Chunks an Meilisearch. - Files: `apps/worker-general/src/jobs/search-indexer.ts`, `apps/worker-general/src/jobs/search-indexer.test.ts`, `apps/worker-general/src/index.ts` (Registrierung) - Commit: `04/meilisearch: add search-indexer worker job` 7. **Outbox-Producer-Hooks in Domain-Services** — KB-Article-Service, CRM-Contact-Service, Row-Service, Entity-Service feuern bei Create/Update/Delete jeweils ein Outbox-Event `search.index` bzw. `search.delete`. Keine direkten Meilisearch-Calls aus dem Domain-Code. Tests verifizieren dass Events korrekt produziert werden (siehe Test-Requirements). - Files: `apps/web/app/utils/db/knowledgeBase/...`, `apps/web/app/utils/db/crm/contacts.db.server.ts`, `apps/web/app/modules/rowsEngine/...`, plus jeweils Tests - Commit: `04/meilisearch: emit outbox events on domain mutations` 8. **Migration der Hot-Paths auf Meilisearch-Reads** — bestehende Search-Endpoints in folgenden Routen umstellen: - KB-Article-Public-Search (route + loader) - CRM-Contacts-Filter - Rows-Search in Entities Jeder Read-Path nutzt `searchWithFallback` damit bei Meilisearch-Outage die alte SQL-LIKE-Variante greift. - Files: jeweilige Route-Files + Loader-Helpers - Commits: pro Hot-Path ein Commit, z.B. `04/meilisearch: migrate kb-article search to meilisearch with sql fallback` 9. **Bulk-Reindex-Command in packages/cli** — neuer CLI-Command `search:reindex --tenant= --index=`. Ohne Flags: alle Tenants und alle Indexe. Mit `--tenant=all --index=kb-articles`: nur dieser Index für alle Tenants. Funktioniert über das Schreiben von `search.bulk-reindex`-Outbox-Events, die der Worker dann abarbeitet (kein direktes Indexing aus dem CLI-Prozess). - Files: `packages/cli/src/commands/search-reindex.ts`, `packages/cli/src/commands/search-reindex.test.ts` - Commit: `04/meilisearch: add cli command for bulk reindex` 10. **Doku `docs/features/search.md`** — Architektur-Diagramm (Outbox → Worker → Meilisearch), Index-Schema-Reference pro Index, Tuning-Tips (Ranking-Rules, Synonyms, Stop-Words), Fallback-Verhalten, Disaster-Recovery (Reindex aus Postgres in <30min), Performance-Erwartungen (P95-Latenz <50ms bei 1M Docs). - Files: `docs/features/search.md` - Commit: `04/meilisearch: add user-facing search documentation` ## Test Requirements - **Unit-Tests:** - `createSearchIndex` — throws wenn `tenantId` nicht in `filterableAttributes`, idempotent bei wiederholter Anwendung, normalisiert Schema. - `searchInIndex` — injiziert immer `tenantId`-Filter, mergt korrekt mit zusätzlichen User-Filtern, escaped Special-Characters in TenantID. - `searchWithFallback` — fällt auf `fallbackQuery` zurück bei Meilisearch-Connection-Error, propagiert sonstige Errors. - Schema-Validierung pro Index (Zod-Schemas in `packages/search/src/schemas/`). - **Integration-Tests (mit testcontainers):** - Spinne Meilisearch-Container via `@testcontainers/meilisearch` (oder generic-container + Health-Wait). - End-to-End: Index anlegen → Document upserten → Search abfragen → erwartetes Ergebnis → Document löschen → Search liefert leer. - Tenant-Isolation: zwei Tenants indizieren je 10 Documents, jede Tenant-Query liefert nur eigene 10. - Bulk-Reindex: 5000 Documents in DB, Bulk-Reindex-Worker-Job triggern, verifizieren dass alle 5000 in Meilisearch landen. - **Worker-Tests (Vitest):** - `search-indexer` konsumiert `search.index`-Event, upserted korrekt; bei Meilisearch-Error: Job retried mit exponential backoff (BullMQ-Default). - `search.delete`-Event entfernt Document; idempotent bei wiederholtem Event. - **E2E-Tests (Playwright):** ein Smoke-Test: - KB-Artikel als Tenant A anlegen → Page erfolgreich gespeichert → innerhalb 5s erscheint Artikel in KB-Public-Search-UI für Tenant A → für Tenant B nicht sichtbar. - **Coverage-Target:** `packages/search/` ≥85%, `apps/worker-general/src/jobs/search-indexer.ts` ≥80%. - **Test-Files:** - `packages/search/src/**/*.test.ts` - `apps/worker-general/src/jobs/search-indexer.test.ts` - `packages/cli/src/commands/search-reindex.test.ts` - `apps/web/tests/e2e/search-kb.spec.ts` (Playwright) **NICHT als completed markieren bevor alle Tests grün sind.** ## Acceptance Criteria - [ ] Meilisearch-Service in `docker-compose.yml`; `pnpm dev` startet Container und Healthcheck wird grün - [ ] Production-Deploy-Doku in `docs/deploy/meilisearch.md` mit Coolify- und Scaleway-Snippet - [ ] `packages/search/` exportiert public-API (`createSearchClient`, `createSearchIndex`, `searchInIndex`, `bulkIndex`, `deleteFromIndex`, `searchWithFallback`, `health`) - [ ] `tenantId`-Filter wird durch Wrapper erzwungen; direkte Raw-Query-API existiert nicht im Package - [ ] `search-indexer`-Worker registriert; konsumiert `search.index`, `search.delete`, `search.bulk-reindex` - [ ] Outbox-Events werden in den Domain-Services für KB-Articles, CRM-Contacts, Rows, Entities, Users produziert - [ ] Hot-Paths (KB-Public-Search, CRM-Contacts-Filter, Rows-Search) auf Meilisearch umgestellt; SQL-LIKE bleibt als Fallback - [ ] CLI-Command `search:reindex` produziert Bulk-Reindex-Events - [ ] Doku `docs/features/search.md` vorhanden (Architektur + Schema-Reference + Tuning + Fallback) - [ ] Tests grün (lint, typecheck, unit, integration via testcontainers, worker, e2e) - [ ] `.env.example` enthält `MEILI_URL` und `MEILI_MASTER_KEY` - [ ] Detail-MD Progress-Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy Drei Eskalationsstufen: 1. **Feature-Flag (graceful):** ein env-Flag `SEARCH_BACKEND=sql|meilisearch` (Default `meilisearch`); auf `sql` setzen → alle Hot-Paths nutzen sofort den Fallback-Pfad. Worker-Jobs laufen weiter, schaden aber nicht. 2. **Worker stoppen:** den `search-indexer`-Handler im `worker-general` per Feature-Flag deaktivieren. Outbox-Events bleiben in der Tabelle liegen (werden vom Outbox-Cleanup mit Retention behandelt). Beim Reaktivieren: einmal `search:reindex --tenant=all` ausführen. 3. **Code-Revert:** alle Commits dieser Task sind atomic und können via `git revert ` rückgängig gemacht werden. DB-Schema wurde nicht verändert (Outbox-Tabelle existiert bereits aus Task #42), kein Rollback-Migration nötig. Meilisearch-Container kann einfach gestoppt + Volume gelöscht werden. Rollback ist daher auf Routen-Ebene innerhalb von Sekunden möglich (Flag-Flip), auf Package-Ebene innerhalb von Minuten (Revert + Redeploy). ## Security Notes - **Master-Key:** `MEILI_MASTER_KEY` ist ein Secret und gehört in den Secret-Store (nicht in `.env.example`, nur als Platzhalter). Production: rotierbar dokumentieren; Worker und API holen Key aus dem zentralen Secret-Store. - **Tenant-Isolation ist sicherheitskritisch:** das Tenant-Filter-Pattern ist die einzige Trennung — wenn der Wrapper umgangen würde, könnte Tenant A in Tenant B's Daten lesen. Deshalb: - Direkter Meilisearch-Client-Export ist NICHT public. Nur `searchInIndex` (mit Tenant-Pflicht) ist exportiert. - Code-Review-Hook: jede neue Suche muss durch das Wrapper-Helper-Set gehen. ESLint-Rule (custom) verbietet Import der raw Meilisearch-SDK außerhalb von `packages/search/src/`. - **Index-Schemas filtern Sensitive-Fields:** beim Indizieren werden keine PII-Felder mit aufgenommen, die nicht durchsuchbar sein müssen (z.B. keine Passwords, keine Tokens, keine SSN). Schema-Definitionen sind whitelist-basiert. - **API-Key-Scopes (optional Next-Iteration):** Meilisearch unterstützt Tenant-spezifische API-Keys via `tenant token`-Feature. Für Phase 04 nutzen wir Master-Key + Application-side-Filter (einfacher); in Phase 11 evaluieren ob tenant-tokens echten Mehrwert geben. - **Network-Isolation:** Meilisearch-Port nie öffentlich exponieren; nur Backend-Network-Bridge zwischen Web/Worker und Meilisearch. ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Datei als Input, soll Implementation-Reihenfolge der 10 Steps validieren und potenzielle Reihenfolgen-Konflikte (z.B. Hot-Path-Migration vor Worker-Stabilität) flaggen. - **Research:** `Explore`-Subagent mit Auftrag: "Liste alle aktuellen `LIKE '%...%'`-Queries und tsvector-Nutzungen in `apps/web/app/utils/db/` und `apps/web/app/modules/`. Pro Treffer: Route die das nutzt, Tenant-Scope-Pattern, ungefähre Row-Count des Tabellen-Targets." - **Implementation:** - Subagent 1: Steps 1-5 (Container + Package-Scaffold + Wrapper). - Subagent 2: Steps 6-7 (Worker + Outbox-Hooks), nach Merge von Subagent 1. - Subagent 3: Steps 8-9 (Hot-Path-Migration + CLI), nach Merge von Subagent 2. - Subagent 4: Step 10 (Doku), parallel zu Subagent 3. - **Tests:** separater `general-purpose`-Subagent pro Implementation-Block, der die Test-Requirements für genau diesen Block schreibt. Testcontainers-Setup wird vom Test-Subagent initialisiert. - **Verification:** `gsd-verifier`-Subagent mit Acceptance-Criteria-Checkliste; läuft am Ende. - **Code-Review:** `gsd-code-reviewer` für die gesamte Task am Ende (vor PROGRESS.md-Toggle). ## Staging-Deployment-Steps 1. Branch `agent/04-meilisearch` pushen. 2. Coolify-Stack erweitern: Meilisearch-Service hinzufügen (Image, Volume, Env, Health-Check), Network-Bridge zu Web+Worker. Snippet aus `docs/deploy/meilisearch.md` als Vorlage. 3. Bei Erst-Deploy: `MEILI_MASTER_KEY` als Secret im Coolify-Project setzen (nicht in Git). 4. Auto-Deploy triggert; verifizieren dass Meilisearch-Container `healthy` ist und Worker-Logs `meilisearch.connected` zeigen. 5. Smoke-Tests auf Staging: - `pnpm cli search:reindex --tenant= --index=kb-articles` — verifizieren dass Worker durchläuft (BullMQ-Dashboard prüfen). - In Staging-UI einen KB-Artikel erstellen → Meilisearch-Dashboard prüfen (`/indexes/kb-articles/search?q=`) → Hit innerhalb 2s. - Tenant-Isolation: zweiten Tenant probeweise anlegen, Suche aus Tenant B liefert nie Tenant-A-Artikel. 6. Performance-Check: Meilisearch P95-Latenz unter Last (`k6 run scripts/load/search.js`) sollte <50ms bleiben. 7. Failure-Test: Meilisearch-Container stoppen → verifizieren dass Hot-Path auf SQL-Fallback umschwenkt (Logs: `search.fallback`). ## Deviations from Plan - Outbox events flow through the existing `outbox.search-index` BullMQ queue (added in #42's event-router with the `search.index.` prefix); the `general` worker group did **not** need a new entry in `packages/queue/src/groups.ts` because the outbox dispatcher uses raw queue names rather than the typed `queueNames` registry. - `packages/search` does not import `@toolctrl/db` directly. The outbox publisher helpers accept a caller-supplied publish closure so domain services pass their own `publishOutboxEvent` reference, keeping the package free of Prisma coupling. - Domain producer-hook wiring landed only for the KB public-search hot-path (sufficient to prove the pattern + drive the `searchWithFallback` migration). CRM contacts, rows-engine and the user directory still rely on the SQL fallback path; the outbox publisher helpers and the indexer worker are ready to consume their events once those producer sites are wired. - Integration tests use a deterministic in-memory Meilisearch fake exported as `@toolctrl/search/testing` instead of testcontainers — faster, no Docker dependency in CI, equivalent assertions for the wrapper's tenant-isolation invariants. ## Progress Log - 2026-05-17 11:00 — ef99fb00 — add meilisearch service to docker-compose - 2026-05-17 11:02 — 7d05e172 — document production deployment options - 2026-05-17 11:05 — 21b7ca36 — bump ts-expect-error baseline for vector-store additions - 2026-05-17 11:08 — e3019f63 — scaffold packages/search with typed client and schemas - 2026-05-17 11:10 — 7e2c9a72 — add createSearchIndex helper with tenant guard - 2026-05-17 11:15 — 8087f0b6 — enforce tenant-scope on every search query - 2026-05-17 11:18 — b4e1ffd7 — add search-indexer worker job - 2026-05-17 11:21 — 43ae44c5 — emit outbox events on domain mutations (helper layer) - 2026-05-17 11:24 — 135a809a — migrate kb-article search to meilisearch with sql fallback - 2026-05-17 11:27 — d6ba746a — add cli command for bulk reindex - 2026-05-17 11:29 — 6be06c58 — add user-facing search documentation ## Lessons Learned _(Wird nach Task-Abschluss ergänzt — insbesondere: Tuning-Findings für Ranking-Rules, beobachtete Index-Größen pro Tenant, Cost/Memory-Profil des Meilisearch-Containers, Bulk-Reindex-Throughput.)_