Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/04-search-rag/meilisearch.md
T

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 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 = "<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

  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:
    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<string, string[]>,
    })
    
    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=<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 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 <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_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=<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.
  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.)