Skip to content

Architektur

Jump to bottom
MadGapun edited this page Jul 14, 2026 · 8 revisions

Architektur

Systemuebersicht

PBP laeuft als lokaler MCP-Server, der ueber das stdio-Protokoll mit Claude Desktop kommuniziert. Das Web-Dashboard bietet eine Browser-Oberflaeche fuer Visualisierung und Interaktion.

┌──────────────────┐      stdio MCP      ┌──────────────────┐
│  Claude Desktop  │◄───────────────────►│   PBP MCP-Server │
└──────────────────┘                      │   (FastMCP 2.x)  │
                                          │                  │
┌──────────────────┐      HTTP/JSON       │   - 177 Tools    │
│  Web-Dashboard   │◄────────────────────►│   - 24 Prompts   │
│   (FastAPI +     │                      │   - Auto-Engine  │
│    React/Vite)   │                      │   - Elwosa       │
└──────────────────┘                      └────────┬─────────┘
                                                   │
                                          ┌────────┴─────────┐
                                          │   SQLite (WAL)   │
                                          │   Schema v48     │
                                          └──────────────────┘
                                                   │
                                          ┌────────┴─────────┐
                                          │  Lokale AI       │
                                          │  (Ollama, optional)│
                                          └──────────────────┘

Tech-Stack

Komponente Technologie
MCP-Server Python 3.11+, FastMCP 2.12+
Web-Dashboard Backend FastAPI (im selben Process)
Web-Dashboard Frontend React 18 + Vite + Tailwind
Datenbank SQLite (WAL-Mode), Schema v48
Lokale AI Ollama (optional, modular per Task)
Scraper httpx (parallel) + Playwright (sequenziell)
CV/Doku-Parsing Mammoth (DOCX), pypdfium2 (PDF), Pillow (Bild)
PDF-Export Playwright (HTML → PDF)
Excel-Export openpyxl
MCP Bridge stdio Transport

Daten-Modell (Schema v48)

Wichtigste Tabellen:

Tabelle Zweck
profiles Mehrere Profile pro User
profile_settings Pro-Profil-Settings (Elwosa, Tonfall, etc.)
skills Skills mit start_year, end_year, level_current
positions Berufserfahrung mit Datum-Range
educations Ausbildung
projects Referenzprojekte mit Skills-Zuordnung
documents CV-Varianten, Anschreiben, Zeugnisse; lifecycle aktiv/archiviert/veraltet (#657)
jobs Stellen mit Hash, Source, Score, Description
applications Bewerbungen mit Lifecycle-Status
application_events Status-Aenderungen mit Datum
application_jobs Many-to-many Bewerbung ↔ Stelle
tasks Freie ToDos pro Bewerbung (#666, Schema v45)
follow_ups Geplante Nachfass-Termine
meetings Termine mit Aufwand
contacts Kontakte (Recruiter, HM, etc.)
contact_categories Farbige Kategorien (#607)
dismiss_reasons Editierbare Ablehnungsgründe, is_active (#663, Schema v45)
search_criteria Suchkriterien inkl. keywords_minus weiche Abwertung (#667)
research_notes Strukturierte Recherchen pro Bewerbung/Stelle (#674, Schema v46)
emails Klassifizierte Mails
user_activity_events Lern-System: User-Aktionen (#594)
learning_insights Lern-System: aggregierte Patterns
elwosa_messages Elwosa-Stream pro Profil
elwosa_pending_lines Von Claude vorgeschlagene neue Linien

Wichtige Services (services/)

  • llm_service.py — TaskKind-Routing-Tabelle (Local/Claude/Manual). Tasks: classify_document, extract_skills, match_job_to_skills, classify_email, analyze_user_patterns, generate_cover_letter, ...
  • profile_classifier.py — Heuristische Profil-Cluster-Erkennung (#590), 9 Cluster + Quellen-Empfehlung
  • scraper_health.py — Auto-Reactivate-Backoff bei silent failures
  • elwosa.py + elwosa_lines.py — Trigger-Engine + Linien-Pool fuer Elwosa
  • wiki_snippets.py — Loader fuer kontextuelle Wiki-Hints (#623)
  • workspace_service.py — Berechnet „Naechster sinnvoller Schritt" fuer das Dashboard
  • learning_service.py — Pattern-Aggregation fuer das Lern-System

Auto-Engine

/api/auto-actions/run triggert in Reihenfolge:

  1. _run_auto_expire — Bewerbungen abgelaufen
  2. _run_auto_followup_reconciler — Nachfass-Termine planen
  3. _run_auto_classify_emails — Mails klassifizieren (lokale AI)
  4. _run_auto_classify_documents — Dokumente klassifizieren (lokale AI)
  5. _run_analyze_user_patterns — Lern-System Pattern-Analyse
  6. _run_scraper_probe — paused Scraper auf Reactivate pruefen
  7. _run_extract_contacts — Kontakte aus Bewerbungen extrahieren
  8. _run_auto_refetch_descriptions — fehlende Beschreibungen nachladen (max 8/Lauf, mit Backoff)
  9. _run_elwosa_speak — Elwosa-Trigger-Engine

Frontend ruft den Endpoint heuristisch wenn das Dashboard offen ist (beim Tab-Aktivieren, sonst stuendlich).

Daten-Pfade

OS Pfad
Windows %LOCALAPPDATA%\BewerbungsAssistent\data\
macOS ~/.bewerbungs-assistent/
Linux ~/.bewerbungs-assistent/

Backups: automatisch beim Schema-Migration in data/backups/.

Anti-DB-Bypass-Pattern (#514)

Claude (und alle MCP-Tools) duerfen NICHT direkt in die SQLite schreiben. Alle Mutationen laufen ueber definierte Helper-Methoden, damit Lifecycle (Audit-Logs, dismiss_counts, Lerneffekt, Statistik) konsistent durchlaeuft. pbp_capabilities und pbp_grenze_melden decken Edge-Cases ab.

Schema-Migrationen

ALTER-only (keine Daten-Migrationen). Bei jedem Server-Start prueft _migrate ob die DB-Schema-Version unter SCHEMA_VERSION liegt und fuehrt incremental ALTER-Statements aus. Vor der ersten Migration erstellt PBP automatisch ein Backup in data/backups/.

Sicherheits-Modell

  • Alles laeuft lokal auf deinem Rechner
  • Keine Telemetrie ohne explizite Opt-in-Zustimmung
  • MCP-Bridge ueber stdio — keine Netzwerk-Ports
  • Web-Dashboard auf localhost:8765 (nur lokal)
  • DSGVO-Funktionen (Loeschung, Export) in der Gefahrenzone
  • Anti-DB-Bypass stellt sicher dass Claude nichts unkontrolliert schreibt

Erweiterbarkeit

Plugin-Plattform (#504) ist fuer v1.8 geplant — soll Mail-Integrationen, Newsletter-Ingest und andere optionale Features als Plug-Ins ermoeglichen statt im Kern-Code.

Home

🗺 Plan

Einstieg

Tabs

Features

Reference

Clone this wiki locally