breakpilot-compliance/docs-src/services/document-crawler/index.md

Document Crawler & Auto-Onboarding

Der Document Crawler ist ein eigenstaendiger Python/FastAPI-Microservice, der automatisch lokale Dateisysteme nach bestehenden Compliance-Dokumenten durchsucht, diese mittels LLM klassifiziert, in IPFS archiviert und eine Compliance-Lueckenanalyse durchfuehrt.

Architektur

graph LR
    FE[Frontend Admin-v2] -->|API Proxy| DC[Document Crawler :8098]
    DC -->|LLM Klassifizierung| SDK[AI Compliance SDK :8090]
    DC -->|IPFS Archivierung| DSMS[DSMS Gateway :8082]
    DC -->|Daten| PG[(PostgreSQL)]

Eigenschaft	Wert
Service	document-crawler
Port	8098
Container	bp-compliance-document-crawler
Sprache	Python 3.11 / FastAPI
Datenbank	PostgreSQL (breakpilot_db)

Features

• Filesystem Crawling — Automatisches Scannen lokaler Verzeichnisse und NAS-Shares
• Delta-Erkennung — SHA-256 Hash-basierte Aenderungserkennung, nur geaenderte Dateien werden erneut verarbeitet
• Text-Extraktion — PDF (PyMuPDF), DOCX (python-docx), XLSX (openpyxl), PPTX (python-pptx)
• LLM-Klassifizierung — Automatische Kategorisierung via AI Compliance SDK
• Keyword-Fallback — Heuristische Klassifizierung wenn LLM nicht verfuegbar (Confidence max 0.3)
• IPFS-Archivierung — Langzeit-Archivierung ueber DSMS Gateway
• Gap-Analyse — Vergleich gefundener Dokumente gegen Compliance-Matrix
• Onboarding-Report — Compliance-Score, fehlende Dokumente, Handlungsempfehlungen

Dokumentklassifizierungen

Kategorie	Beschreibung
VVT	Verzeichnis von Verarbeitungstaetigkeiten
TOM	Technische und organisatorische Massnahmen
DSE	Datenschutzerklaerung
AVV	Auftragsverarbeitungsvertrag
DSFA	Datenschutz-Folgenabschaetzung
Loeschkonzept	Loeschfristen und -verfahren
Einwilligung	Einwilligungserklaerungen
Vertrag	Vertraege mit Datenschutzbezug
Richtlinie	Interne Datenschutzrichtlinien
Schulungsnachweis	Datenschutz-Schulungszertifikate
Sonstiges	Nicht klassifizierbare Dokumente

Datenbank-Schema

4 Tabellen (Migration 014):

crawler_sources

Konfigurierbare Crawl-Verzeichnisse mit Pfad, Dateityp-Filter, Tiefenbegrenzung und Ausschlussmustern.

crawler_jobs

Jede Crawl-Ausfuehrung mit Status (pending/running/completed/failed), Typ (full/delta) und Statistiken.

crawler_documents

Jede entdeckte Datei mit Metadaten, extrahiertem Text, Klassifizierung, Confidence-Score und Archivierungsstatus.

crawler_onboarding_reports

Zusammenfassungsberichte mit Compliance-Score, Klassifizierungs-Aufschluesselung und Gap-Analyse.

API Endpoints

Alle unter /api/v1/crawler/, benoetigen X-Tenant-ID Header.

Quellen (Sources)

Method	Endpoint	Beschreibung
GET	/sources	Crawl-Quellen auflisten
POST	/sources	Neue Quelle erstellen
PUT	/sources/{id}	Quelle aktualisieren
DELETE	/sources/{id}	Quelle loeschen
POST	/sources/{id}/test	Konnektivitaet testen

Jobs

Method	Endpoint	Beschreibung
POST	/jobs	Crawl starten (full/delta)
GET	/jobs	Jobs auflisten
GET	/jobs/{id}	Job-Details + Fortschritt
POST	/jobs/{id}/cancel	Laufenden Job abbrechen

Dokumente

Method	Endpoint	Beschreibung
GET	/documents	Dokumente auflisten (Filter: classification, status)
GET	/documents/{id}	Dokument-Details + Text-Vorschau
PUT	/documents/{id}/classify	Manuelle Klassifizierungs-Korrektur
POST	/documents/{id}/archive	In IPFS archivieren
POST	/documents/archive-batch	Bulk-Archivierung

Reports

Method	Endpoint	Beschreibung
POST	/reports/generate	Onboarding-Report generieren
GET	/reports	Reports auflisten
GET	/reports/{id}	Report mit Gap-Analyse

Gap-Analyse

Die Gap-Analyse vergleicht gefundene Dokumenttypen gegen eine Pflichtdokumenten-Matrix:

Dokument	Pflicht fuer	Severity
VVT	Alle Unternehmen	CRITICAL
TOM	Alle Unternehmen	CRITICAL
DSE	Alle Unternehmen	CRITICAL
Loeschkonzept	Alle Unternehmen	HIGH
AVV	Auftragsverarbeiter	HIGH
DSFA	KI-Nutzer, Hochrisiko-Verarbeitung	HIGH
Schulungsnachweis	Alle Unternehmen	MEDIUM
Richtlinie	Alle Unternehmen	MEDIUM

Frontend

4-Tab-Seite unter /sdk/document-crawler:

1. Quellen — Crawl-Verzeichnisse konfigurieren, Konnektivitaet testen
2. Crawl-Jobs — Crawl starten, Fortschrittsbalken mit Auto-Refresh, Job-Historie
3. Dokumente — Tabelle mit Klassifizierungs-Badges, Confidence-Bars, Reklassifizierung, Archivierung
4. Onboarding-Report — SVG Compliance-Score Ring, Gap-Analyse mit Severity-Cards

Konfiguration

Umgebungsvariable	Standard	Beschreibung
PORT	8098	Service-Port
DATABASE_URL	-	PostgreSQL Connection String
LLM_GATEWAY_URL	http://ai-compliance-sdk:8090	LLM Service URL
DSMS_GATEWAY_URL	http://dsms-gateway:8082	IPFS Service URL
CRAWL_BASE_PATH	/data/crawl	Basis-Pfad im Container
MAX_FILE_SIZE_MB	50	Maximale Dateigroesse

Health Check

curl http://localhost:8098/health
# {status: healthy, service: document-crawler}