Systemarchitektur & Technisches Handbuch (Förder-Cockpit)

Dieses Handbuch dokumentiert die vollständige Softwarearchitektur, Modulstruktur, Technologieauswahl und Entwicklungsstandards des Förder-Cockpits.

1. Technologie-Stack & Design-Prinzipien

2. Modul-Übersicht (src/foerder_cockpit/modules/)

Das System ist nach Domain-Driven-Design (DDD) in klar abgegrenzte Module unterteilt:

graph TD
    UI["WebUI (FastAPI + HTMX + Jinja2)"] --> Modules
    API["REST API (/api/v1/...)"] --> Modules

    subgraph Modules["Fachmodule im Förder-Cockpit"]
        Subsidies["subsidies\n(Förderfälle, Fristen, BAFA/KfW-Status)"]
        Customers["customers\n(Kunden & Liegenschaften)"]
        Documents["documents\n(Intake, Triage, Parallele Worker, OCR)"]
        Calculations["calculations\n(Heizlast DIN EN 12831, Förderquoten)"]
        Knowledge["knowledge\n(pgvector Vektorsuche, Jev Relevanzfilter)"]
        Vault["vault\n(Obsidian Sync, Private Git Automation)"]
        Privacy["privacy\n(DualLLMGateway, PII Sanitizer & Redaction)"]
        Assistant["assistant\n(KI-Fallassistent, Dokumenten-Q&A)"]
        Onboarding["onboarding\n(Ersteinrichtung, Systemchecks, Secrets)"]
        Integrations["integrations\n(IMAP E-Mail-Postfach, Lexware API)"]
    end

    Subsidies --> DB[(PostgreSQL)]
    Customers --> DB
    Documents --> DB
    Knowledge --> DB

Die Module im Detail:

1. subsidies (Förderfall-Management):
2. Verwaltung von Förderprogrammen (BEG EM, KfW 458, EBW / iSFP, BEG WG).
3. Automatische Normalisierung und Validierung von Vorgangsnummern (93124661), BND-, TPB-, TPN- und iSFP-Nummern.

4. Fristenmanagement (z. B. 36 Monate Bewilligungszeitraum) mit visueller Ampel-Warnung.

5. customers (Kunden- und Liegenschaftsverwaltung):

6. Kundenstammdaten (Name, Telefon, E-Mail).

7. Verknüpfte Liegenschaften mit genauer Postanschrift, Baujahr und Wohneinheiten.

8. documents (Paralleler Dokumenten-Posteingang & Triage):

9. Überwacht das Verzeichnis data/Eingang/.
10. Parallele Verarbeitung von PDF-Batches (8 Worker gleichzeitig via asyncio.Semaphore).
11. Zweistufige Textextraktion: Nativer PDF-Text (pypdf) mit automatischem Tesseract-OCR Fallback für Scans.

12. Intelligente Zuordnung nach Vorgangsnummer oder Name/Adresse; unklare Fälle wandern in Quarantäne (_unklar/).

13. calculations (Technische & Wirtschaftliche Berechnungen):

14. DIN-konforme Heizlastabschätzung nach Baualtersklasse und beheizter Wohnfläche.

15. Förderrechner 2026: Grundförderung (30 %), Geschwindigkeitsbonus (+20 %), Einkommensbonus (+30 %), Effizienzbonus (+5 %), Kältemittelbonus (+5 %) mit automatischer Deckelung auf maximal 70 % Zuschuss.

16. privacy (Datenschutz & Modell-Routing):

17. PrivacySanitizer: Maskiert sensible Kundendaten (Namen, Anschriften, IBANs) in pseudonymisierte Tokens ([KUNDE_1], [ADRESSE_1]).

18. DualLLMGateway: Routet bevorzugt an ein lokales LLM (Ollama) ohne Datenabfluss; bei Cloud-Anfragen (Anthropic) werden ausschließlich zensierte Daten übertragen.

19. assistant (KI-Fallassistent & Dokumenten-Q&A):

20. Erlaubt Fragen zur gesamten Akte direkt im WebUI (/faelle).

21. Injiziert Antragsdaten, Fristen und Auszüge der hinterlegten Dokumente in den System-Prompt.

22. vault (Obsidian & Git-Synchronisation):

23. Exportiert Förderfälle und Förderrichtlinien als saubere Markdown-Notizen in den Obsidian Vault.

24. Prüft vor dem Zugriff per automatischem git fetch auf Remote-Änderungen und pusht lokale Notizänderungen via hinterlegtem SSH-Schlüssel in ein privates GitHub-Repository.

25. onboarding (Assistent für Ersteinrichtung):

26. Führt neue Anwender Schritt für Schritt durch die Konfiguration:
    1. PostgreSQL & pgvector Datenbankverbindung
    2. TypeSafe AI API-Schlüssel für JEV-Entscheidungen
    3. Lokales LLM (Ollama) & Cloud-Fallback (Anthropic)
    4. IMAP E-Mail-Postfach für automatischen Fristen-Empfang
    5. Lexware Office API für Rechnungsstellung
    6. Obsidian Vault & privates GitHub-Backup

3. Qualitätskriterien & Prüfregeln (AGENTS.md)

Für sämtliche Code-Änderungen gelten strikte Richtlinien:
1. Typensicherheit: uv run pyrefly check muss zu jedem Zeitpunkt 0 Fehler melden.
2. Linting: uv run ruff check . mit maximal 120 Zeichen Zeilenlänge muss 0 Warnungen/Fehler melden.
3. Tests: Sämtliche Unit-, Integrations- und Playwright-E2E-Tests müssen zu 100 % erfolgreich durchlaufen (pytest).
4. PyCharm Code-Inspektionen: Vor und nach Merges auf den Hauptarbeitszweig (complete-rework) muss eine Überprüfung via PyCharm Inspections (lint_files) erfolgen (0 ungelöste Referenzen, 0 fatale Fehler).
5. Git Hygiene: Feature-Branches (feature/...), schmale Staging-Bereiche (git add <files>), kein git commit -a, saubere Fast-Forward Merges.