19 KiB
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 imworker-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 = "<id>" 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
- Meilisearch-Container in docker-compose.yml ergänzen — neuer Service
meilisearchmit Imagegetmeili/meilisearch:v1.8, Volume für persistenten Index, Health-Check, ENV-VarsMEILI_MASTER_KEYundMEILI_ENV=development(lokal) bzw.MEILI_ENV=production(staging/prod).- Files:
docker-compose.yml,docker-compose.dev.yml(falls separat),.env.examplemitMEILI_URL=http://localhost:7700,MEILI_MASTER_KEY=devkey - Commit:
04/meilisearch: add meilisearch service to docker-compose
- Files:
- 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
- Files:
- 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 inpackages/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
- Files:
- Index-Helper
createSearchIndeximplementieren — wrapper-Funktion die idempotent ein Meilisearch-Index anlegt oder updated. Signatur:Helper validiert dasscreateSearchIndex({ 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<string, string[]>, })tenantIdinfilterableAttributesenthalten 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
- Files:
- Tenant-Scoped Query-Wrapper —
searchInIndex({ index, tenantId, query, filters?, sort?, limit?, offset? }). Intern wird der Filter immer mittenantId = "${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
- Files:
- Indexer-Worker im worker-general registrieren — neuer BullMQ-Job-Handler
search.index,search.delete,search.bulk-reindex. Konsumiert Outbox-Events vom Job-Producer (sieheoutbox-pattern.md). Event-Payload:{ tenantId, indexName, documentId, document? }. Beisearch.index→ upsert; beisearch.delete→ delete-by-primaryKey; beisearch.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
- Files:
- 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.indexbzw.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
- Files:
- 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
searchWithFallbackdamit 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
- Bulk-Reindex-Command in packages/cli — neuer CLI-Command
search:reindex --tenant=<id?> --index=<name?>. Ohne Flags: alle Tenants und alle Indexe. Mit--tenant=all --index=kb-articles: nur dieser Index für alle Tenants. Funktioniert über das Schreiben vonsearch.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
- Files:
- 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
- Files:
Test Requirements
- Unit-Tests:
createSearchIndex— throws wenntenantIdnicht infilterableAttributes, idempotent bei wiederholter Anwendung, normalisiert Schema.searchInIndex— injiziert immertenantId-Filter, mergt korrekt mit zusätzlichen User-Filtern, escaped Special-Characters in TenantID.searchWithFallback— fällt auffallbackQueryzurü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.
- Spinne Meilisearch-Container via
- Worker-Tests (Vitest):
search-indexerkonsumiertsearch.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.tsapps/worker-general/src/jobs/search-indexer.test.tspackages/cli/src/commands/search-reindex.test.tsapps/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 devstartet Container und Healthcheck wird grün - Production-Deploy-Doku in
docs/deploy/meilisearch.mdmit 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 Packagesearch-indexer-Worker registriert; konsumiertsearch.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:reindexproduziert Bulk-Reindex-Events - Doku
docs/features/search.mdvorhanden (Architektur + Schema-Reference + Tuning + Fallback) - Tests grün (lint, typecheck, unit, integration via testcontainers, worker, e2e)
.env.exampleenthältMEILI_URLundMEILI_MASTER_KEY- Detail-MD Progress-Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
Drei Eskalationsstufen:
- Feature-Flag (graceful): ein env-Flag
SEARCH_BACKEND=sql|meilisearch(Defaultmeilisearch); aufsqlsetzen → alle Hot-Paths nutzen sofort den Fallback-Pfad. Worker-Jobs laufen weiter, schaden aber nicht. - Worker stoppen: den
search-indexer-Handler imworker-generalper Feature-Flag deaktivieren. Outbox-Events bleiben in der Tabelle liegen (werden vom Outbox-Cleanup mit Retention behandelt). Beim Reaktivieren: einmalsearch:reindex --tenant=allausführen. - Code-Revert: alle Commits dieser Task sind atomic und können via
git revert <range>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_KEYist 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/.
- Direkter Meilisearch-Client-Export ist NICHT public. Nur
- 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 aktuellenLIKE '%...%'-Queries und tsvector-Nutzungen inapps/web/app/utils/db/undapps/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-reviewerfür die gesamte Task am Ende (vor PROGRESS.md-Toggle).
Staging-Deployment-Steps
- Branch
agent/04-meilisearchpushen. - Coolify-Stack erweitern: Meilisearch-Service hinzufügen (Image, Volume, Env, Health-Check), Network-Bridge zu Web+Worker. Snippet aus
docs/deploy/meilisearch.mdals Vorlage. - Bei Erst-Deploy:
MEILI_MASTER_KEYals Secret im Coolify-Project setzen (nicht in Git). - Auto-Deploy triggert; verifizieren dass Meilisearch-Container
healthyist und Worker-Logsmeilisearch.connectedzeigen. - Smoke-Tests auf Staging:
pnpm cli search:reindex --tenant=<staging-tenant-id> --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=<title>) → Hit innerhalb 2s. - Tenant-Isolation: zweiten Tenant probeweise anlegen, Suche aus Tenant B liefert nie Tenant-A-Artikel.
- Performance-Check: Meilisearch P95-Latenz unter Last (
k6 run scripts/load/search.js) sollte <50ms bleiben. - 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-indexBullMQ queue (added in #42's event-router with thesearch.index.prefix); thegeneralworker group did not need a new entry inpackages/queue/src/groups.tsbecause the outbox dispatcher uses raw queue names rather than the typedqueueNamesregistry. packages/searchdoes not import@toolctrl/dbdirectly. The outbox publisher helpers accept a caller-supplied publish closure so domain services pass their ownpublishOutboxEventreference, 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
searchWithFallbackmigration). 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/testinginstead 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.)