Zum Inhalt

Knowledge-Hub-Modul — Architektur-Konzept (v2)

Status: Konsolidierter Entwurf Zielversion: v2.0.0 Aufwand: ~150h Abhängigkeiten: Multi-Tenancy-Fundament v1.0.0, Konnektor-Welle 1 + Teile Welle 2 Trigger: Start nach 2-3 Monaten AVS-Feedback-Phase zum v1.0.0-Fundament Letzte Aktualisierung: 2026-04-17

Änderungshistorie v1 → v2

Änderung Grund
Frontend-Stack: Vue 3 ohne Pinia festgelegt Plattform-Entscheidung aus Dialog
Aktivierung über tenant_packages Einstufige Freischaltung, kein Lizenz-Gate
UI-Defaults festgelegt Aus Dialog-Block 4: Responsiveness ja, Mobile-First nein, etc.
Timing: 2-3 Monate nach v1.0.0-Launch, nicht parallel Bewusste Lernphase aus Produktivdaten

1. Ziel & Positionierung

Was das Modul liefert

Eine zweite Interaktionsform für das aggregierte Wissen eines Tenants — neben dem Chatbot. Fokus: Such-First, mit Chat als Feature daneben.

Typischer Workflow: 1. User öffnet Knowledge-Hub-UI 2. Tippt Suchbegriff oder Frage 3. Bekommt semantisch rangierte Ergebnisse mit Snippet, Quellen-Badges, Facetten-Filtern 4. Klickt ein Ergebnis → volles Dokument mit Source-Attribution 5. Alternativ: "Chat zu diesem Thema" → springt in Chatbot mit vorgefülltem Kontext

Was das Modul nicht ist

Explizit nicht im Scope:

  • Kein Knowledge-Graph mit Entitäts-Extraktion
  • Keine ML-Personalisierung
  • Kein Governance-Dashboard
  • Kein Document-Lifecycle-Management
  • Keine agentischen Workflows
  • Keine Browser-Extension, keine Desktop-App, keine Mobile-Native-App

Wir bleiben im Pfad B des Gesamtkonzepts: Plattform-Fundament für Tourismus/Verwaltungs-Domäne, nicht horizontales SaaS-Produkt (würde Stufe 3 entsprechen).

Verhältnis zum Chatbot

Beide greifen auf denselben Index zu (Qdrant-Collections des Chatbots + optional Shared-Collections). Beide sehen dieselben Daten. Unterschied: Chatbot ist konversationell + generativ, Knowledge-Hub ist retrieval-fokussiert + explorativ.

Rationale für Timing (festgelegt)

Start nach 2-3 Monaten AVS-Feedback zum v1.0.0-Fundament. Grund: Ohne echte Nutzungsdaten aus produktivem AVS-Betrieb können wir nur raten, ob eine Such-First-UI wirklich angenommen wird oder ob Chat das bevorzugte Paradigma bleibt. Die Lernphase gibt uns Entscheidungsgrundlage.

2. Aktivierung und Scope

2.1 Als Plattform-Modul

Knowledge-Hub ist ein external_eligible Plattform-Modul (knowledge_hub). Einstufige Freischaltung über tenant_packages:

-- Aktivierung pro Tenant durch Operator (AVS):
UPDATE tenant_packages
SET enabled_modules = enabled_modules || '"knowledge_hub"'
WHERE tenant_id = :tenant_id;

Kein Lizenz-Feature-Gate. AVS-Operator entscheidet im Paket-Konfigurations-UI, welche Tenants das Modul bekommen. Preis-Durchreichung an die Kurverwaltung ist Sache von AVS.

2.2 Scope pro Tenant

Aktivierte Tenants haben UI-Route /tenant/knowledge/, die alle Chatbots des Tenants als potentielle Suchquellen anzeigt. Alle Wissensquellen (chatbot_sources) quer über alle Chatbots sind durchsuchbar.

Tenant-User mit tenant-viewer oder höher kann nutzen.

2.3 Nicht-Tenant-übergreifend

Invariante: Knowledge-Hub eines Tenants sieht nie Daten eines anderen Tenants. Die Isolationsgrenze des Multi-Tenancy-Fundaments gilt.

3. Architektur

3.1 Einordnung ins Drei-Schichten-Modell

Das Knowledge-Hub ist eine zusätzliche konsumierende Schicht auf dem Fundament aus v1.0.0 — keine eigene Indexierung, keine eigene Ingestion:

┌─────────────────────────────────────────────────────────┐
│  KONSUMIERENDE SCHICHT                                  │
│  ┌──────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │ Chatbot (v1) │  │ Knowledge-Hub    │  │ API       │  │
│  │              │  │ (v2.0.0)         │  │           │  │
│  └──────┬───────┘  └────────┬─────────┘  └─────┬─────┘  │
│         │                   │                   │       │
└─────────┴───────────────────┴───────────────────┴───────┘
                              │
                              ▼
          ┌─────────────────────────────────┐
          │  Indexierungs-Schicht (v1.0.0)  │
          └─────────────────────────────────┘

3.2 Neue Services

  • Search-Service (src/avs_chatbot/modules/knowledge_hub/search.py): Retrieval-basiert, ohne LLM-Generierung
  • Browse-Service: SQL-basiert, Facet-Aggregation auf document_versions
  • Summary-Service: LLM-Call für on-demand-Dokumenten-Zusammenfassungen, gecached

3.3 Datenmodell-Erweiterungen

Neue Tabellen (alle tenant-scoped, RLS aktiv):

CREATE TABLE kh_bookmarks (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    user_id         VARCHAR(255) NOT NULL,
    document_id     UUID NOT NULL REFERENCES document_versions(id) ON DELETE CASCADE,
    note            TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (user_id, document_id)
);

CREATE TABLE kh_search_history (
    id              BIGSERIAL PRIMARY KEY,
    tenant_id       UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    user_id         VARCHAR(255) NOT NULL,
    query           TEXT NOT NULL,
    result_count    INT,
    searched_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    clicked_doc_ids UUID[]
);

CREATE TABLE kh_saved_searches (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id       UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
    user_id         VARCHAR(255) NOT NULL,
    name            VARCHAR(255) NOT NULL,
    query           TEXT NOT NULL,
    filters         JSONB,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE kh_document_summaries (
    document_id     UUID PRIMARY KEY REFERENCES document_versions(id) ON DELETE CASCADE,
    summary         TEXT NOT NULL,
    language        VARCHAR(5) NOT NULL,
    generated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    model_version   VARCHAR(64)
);

4. UI-Architektur

4.1 Stack (festgelegt in v2)

Vue 3 + Composition API, analog zur Plattform-Entscheidung. Ohne Pinia — State-Weitergabe über Props/Events und bei Bedarf provide/inject.

Search-Listen, Facetten-Filter, Bookmarks-Widget als einzeln mountbare Vue-Apps in bestehende Jinja2-Seiten oder als zusammenhängende Hub-SPA unter /tenant/knowledge/*. Die Entscheidung (SPA vs. teil-eingebettet) wird beim Implementierungsstart getroffen — beide Varianten sind architektonisch kompatibel.

4.2 Routen

/tenant/knowledge/
├── /                  → Landing: Suchfeld + kürzliche Suchen + Bookmarks
├── /search?q=...      → Ergebnisseite mit Facetten
├── /doc/{id}          → Einzeldokument-Detail
├── /source/{id}       → Quellen-Übersicht (alle Docs einer Source)
├── /bookmarks         → Meine Bookmarks
├── /history           → Mein Suchverlauf
└── /saved             → Gespeicherte Suchen

4.3 Landing-Page (Wireframe)

┌────────────────────────────────────────────────────┐
│ Wissensbasis Kurverwaltung Bad Tölz                │
│                                                    │
│ ┌────────────────────────────────────────────────┐ │
│ │ 🔍 Worin wird gesucht? (Was ist Kurtaxe?)      │ │
│ └────────────────────────────────────────────────┘ │
│                                                    │
│ ┌─ Kürzlich gesucht ────────────────────────────┐  │
│ │ Kurtaxe-Berechnung    vor 2h                  │  │
│ │ Meldeschein-Workflow  gestern                 │  │
│ └───────────────────────────────────────────────┘  │
│                                                    │
│ ┌─ Bookmarks ──┐ ┌─ Quellen-Übersicht ──────────┐  │
│ │ 📌 3 Docs    │ │ 📄 42 Uploads                │  │
│ │              │ │ 📚 156 Confluence-Seiten     │  │
│ └──────────────┘ └───────────────────────────────┘  │
└────────────────────────────────────────────────────┘

4.4 Ergebnisseite

(Unverändert zu v1: Filter-Sidebar + Ergebnis-Liste mit Snippet, Source-Badge, Datum, Chat-Button)

4.5 Dokument-Detail

(Unverändert zu v1: KI-Zusammenfassung + Volltext + Source-Attribution + Bookmark + Chat-Option)

4.6 Chatbot-Integration

"Chat zu diesem Dokument" öffnet den zugehörigen Chatbot mit vorgefüllter System-Kontext-Nachricht. Der Chatbot priorisiert das referenzierte Dokument beim Retrieval.

4.7 UI-Defaults (festgelegt in v2)

Thema Default
Volltext-Highlighting highlight.js für Code + eigene Span-Wrapper für Fließtext
Sprachen (UI) DE + EN von Anfang an
Mobile Responsiveness Responsive, aber kein Mobile-First
Keyboard-Shortcuts (/, ⌘K) v2.1.0-Feature, nicht Launch-kritisch
Dokument-Vorschau Voller Download in v2.0.0, Streaming in v2.1.0

5. Technische Umsetzung

5.1 API-Endpoints

GET  /api/v2/knowledge/search
     ?q=<query>&sources=<id1,id2>&chatbots=<id1,id2>
     &date_from=&date_to=&limit=20&offset=0
     → { results, facets, total }

GET  /api/v2/knowledge/documents/{id}
GET  /api/v2/knowledge/documents/{id}/summary
POST /api/v2/knowledge/bookmarks
GET  /api/v2/knowledge/bookmarks
DELETE /api/v2/knowledge/bookmarks/{id}
GET  /api/v2/knowledge/history
POST /api/v2/knowledge/saved-searches

5.2 Search-Algorithmus

  1. Query-Embedding generieren
  2. Parallel über alle relevanten Qdrant-Collections suchen (Chatbot-Collections + optional Shared)
  3. Top-20 pro Collection, Merge + Re-Ranking via Cross-Encoder
  4. Facet-Aggregation auf PostgreSQL-Seite (aus document_versions)
  5. Response: Top-N + Facet-Counts

Performance-Ziel: <1s p95 (deutlich schneller als Chatbot, weil kein LLM-Call).

5.3 Zusammenfassungs-Caching

On-demand generiert, in kh_document_summaries gecached. Invalidierung bei Neuindizierung des Dokuments.

5.4 Permission-Awareness

Das Knowledge-Hub profitiert direkt vom Permission-Framework aus Konnektor-Ausbau (siehe Konnektor-Roadmap §6):

  • Beim Launch (v2.0.0): Wenn Permission-Framework in Phase 1 → alle Tenant-User sehen alles Tenant-interne (keine Filterung)
  • Wenn Phase 2 vorher aktiviert: Automatische Filterung auf User-Gruppen

Der Hub bringt keine eigene Permission-Logik mit.

6. Aktivierungsworkflow

6.1 Operator-Seite (AVS)

  1. Knowledge-Hub-Modul wird beim Deployment installiert (Teil des v2.0.0-Packages)
  2. Operator-Admin: tenant_packages.enabled_modules um knowledge_hub erweitern für gewünschte Tenants

6.2 Tenant-Seite

  1. Tenant-Admin sieht neue Navigation "Wissensbasis" in der Tenant-UI
  2. Einmalige Einrichtung: welche Chatbots im Hub durchsuchbar? (Default: alle)
  3. Nutzung beginnt

7. Was wir NICHT aus Chatbot-Logik erben

  • Kein Chat-History
  • Keine Guardrails (kein LLM-Call in Hauptinteraktion)
  • Kein Thumb-up/down-Feedback — stattdessen Click-Tracking
  • Kein Rate-Limiting auf Such-Ebene, nur generisch auf API

8. Aufwandsschätzung

Block Aufwand
1. Frontend-Framework-Setup (Vue 3 + Build) 12h
2. Datenmodell-Migration (4 neue Tabellen) 8h
3. Search-Service 24h
4. Browse-Service 12h
5. Summary-Service + Caching 12h
6. UI — Landing-Page + Suchfeld 8h
7. UI — Suchergebnisse mit Facetten 20h
8. UI — Dokument-Detail 16h
9. UI — Bookmarks + History + Saved-Searches 12h
10. Chatbot-Integration ("Chat zu diesem Dok") 8h
11. API-Endpoints 12h
12. Permission-Integration (nutzt vorhandenes Framework) 8h
13. Testing + Dokumentation 14h
Total ~166h

Realistisch ~150-170h.

8.1 Reduktionen

  • Block 9 in v2.1.0 verschieben: -12h
  • Block 10 in v2.1.0 verschieben: -8h
  • Summary-Caching minimal (nur on-demand, kein Store): -4h

Minimal-Scope: ~130h

9. Phasierung

Phase I — Backend-Services (~56h)

Blöcke 2, 3, 4, 5, 11.

Phase II — Core-UI (~56h)

Blöcke 1, 6, 7, 8.

Phase III — Ergänzungen (~54h)

Blöcke 9, 10, 12, 13.

Kalenderzeit: ~4-5 Wochen fokussiert.

10. Voraussetzungen

  1. Multi-Tenancy-Fundament v1.0.0 steht
  2. Mindestens 2-3 Konnektor-Typen implementiert (Welle 1)
  3. 2-3 Monate AVS-Produktivbetrieb als Lernphase durchlaufen
  4. Permission-Framework Phase 1 reicht; Phase 2 wäre Bonus
  5. Vue-3-Build-Infrastruktur aus v1.0.0 bereits etabliert

11. Erfolgs-Kennzahlen

Metrik Ziel (3 Monate nach Launch)
Monthly Active Users pro Tenant >50% der Tenant-User
Searches pro User pro Monat >10
Click-Through-Rate auf Ergebnisse >40%
Time-to-Found (median) <20s
"Chat zu diesem Dok"-Nutzung >15% der Dokument-Views
Bookmarks pro aktivem User >3

Zweck: Verstehen, ob Such-Paradigma angenommen wird oder Chat dominiert.

12. Geklärte und offene Punkte

Geklärt (aus Dialog)

  • ✅ Vue 3 + Composition API als Stack
  • ✅ Timing: nach 2-3 Monaten AVS-Feedback
  • ✅ Aktivierung über tenant_packages, kein Lizenz-Gate
  • ✅ DE + EN von Anfang an
  • ✅ Responsive, aber kein Mobile-First
  • ✅ Keyboard-Shortcuts und Stream-Preview in v2.1.0

Offen (Feinheiten, erst beim Implementierungsstart)

  • SPA vs. teil-eingebettete Vue-Komponenten (hängt an AVS-Feedback zum Admin-UI-Gefühl)
  • Facetten-Detailumfang (welche Metadaten werden zu Filtern?)
  • Volltext-Viewer-Integration für PDFs (Browser-nativ oder PDF.js?)

13. Was als Nächstes

Dieses Konzept wird nicht direkt umgesetzt, sondern nach der AVS-Feedback-Phase erneut validiert. Vor der Implementierung sollten gesehen werden:

  1. AVS-Nutzungsdaten aus ~2-3 Monaten Produktivbetrieb
  2. Welche Konnektoren realistisch bis dahin implementiert sind
  3. Bedarfsabschätzung: Wie viele Tenant-User pro aktiviertem Modul können wir erwarten?

Falls sich in dieser Phase zeigt, dass der Chatbot die Such-Bedürfnisse ausreichend bedient, kann das Modul verschoben oder reduziert werden. Falls Such-First-Bedarf deutlich wird: Dieses Konzept wird zur Umsetzungsgrundlage.