# KI-BauIN – Tech-Stack

Stand: 2. Oktober 2026. Grundlage ist die allgemeine Tech-Stack-Referenz einer bestehenden
Laravel-Verwaltungsanwendung (Kollegenprojekt). Dieses Dokument übernimmt deren Grundsätze
und benennt, wo KI-BauIN bewusst abweicht und warum.

## Beteiligte

- **ITM:** Anbieter der KI-API (über API-Werk: Dokumentdienst mit OCR, Embeddings, Reranker,
  Sprachmodell), Projektleitung und abrechnende Firma. Stellt auch die Server (Staging, Produktion) und den Gitea, auf den das
  Repository gespiegelt wird.
- **BauIn:** Endkunde. Prüft als Bauüberwachung im Auftrag der DB Nachträge dem Grunde nach.
  Liefert Fachdaten (LVs, Nachträge, Bewertungsmatrizen), stellt den Fachexperten und nutzt das System.
- „Kunde“ meint in diesem Dokument BauIn; wo ITM gemeint ist, steht ITM.

## 1. Backend und Oberfläche

| Technologie | Einsatz | Vergleich zur Referenz |
|---|---|---|
| PHP 8.5 | Laufzeit (Entwicklung und Produktion gleich) | abweichend (Referenz: 8.4), siehe Abschnitt 6 |
| Laravel 13 | Framework | gleich |
| Livewire 4, klassenbasierte Komponenten | Interaktive Oberfläche; Klasse plus separate Blade-View | abweichend (Referenz: Livewire 3) |
| Blade | Templates, Layouts, eigene Komponenten | gleich |
| Tailwind CSS 4 | Gestaltung | gleich |
| TallStackUI 4 (Präfix `ts-`) | UI-Komponenten | Version abweichend (Referenz: 3) |
| Laravel Fortify | Login, Passwort-Reset, E-Mail-Bestätigung, 2FA, Passkeys | ergänzt |
| Mehrsprachigkeit | Deutsch (Standard) und Englisch, Sprache je Benutzer; Übersetzungen über Laravel Lang (nur Entwicklung), eigene Texte in `lang/project/` | ergänzt |
| Vite 8, Node.js/npm | Asset-Build | gleich |
| Composer | Abhängigkeiten mit Lockfile | gleich |
| GAEB-Import | LVs und Nachtrags-LVs aus GAEB DA XML (X86); D86 nur als Rückfall | ergänzt |
| pdf.js (lokal ausgeliefert, kein CDN) | Anzeige der LV- und Nachtrags-PDFs mit Sprung zur Fundstelle | ergänzt |
| PhpSpreadsheet | Ergebnisliste als Excel; Option: Bewertungsmatrix in der Vorlage der DB | geplant |
| PHPWord | Option: Stellungnahme aus Word-Vorlage (nur .docx) | Option |
| Dompdf | PDF-Erzeugung | vorerst nicht nötig |

Aufbau als modularer Laravel-Monolith: Livewire-Komponenten für die Interaktion, Services für
fachliche Abläufe, Eloquent-Modelle für die Daten, Policies und Spatie-Rollen für den Zugriff.
Länderspezifisches (DE/AT) hinter Schnittstellen im Kern, Umsetzungen in `app/Laender/…`.

## 2. Daten und Hintergrundverarbeitung

| Baustein | Umsetzung | Vergleich zur Referenz |
|---|---|---|
| MySQL 8.4 LTS | Anwendungsdaten, Rechte, Protokoll; Rohvektoren als BLOB | gleich (Vektoren ergänzt) |
| Eloquent, Migrationen | Datenmodell und Schemaänderungen | gleich |
| Privater Dateispeicher | Uploads (Verträge, LVs, MKAs); Auslieferung nur mit Rechteprüfung | gleich |
| Datenbank-Warteschlange | Dokumentverarbeitung, Embeddings, KI-Aufrufe | gleich |
| Laravel Scheduler | Wiederanlauf hängender Aufträge, Aufräumarbeiten | gleich |
| Meilisearch | Hybride Suche (Volltext + Vektoren) mit Rechte-Filtern; Index jederzeit aus MySQL neu aufbaubar | ergänzt |
| KI-API ITM (API-Werk, `https://api-werk.de`) | Dokumentdienst (OCR-Gateway/OpenDataLoader: PDF → Markdown/JSON, asynchron mit Abfrage des Ergebnisses), Modelle `embed`, `rerank`, `chat`, `chat-noreasoning` (OpenAI-kompatibel). Drei Schlüssel, nur im Backend; 120 Anfragen/min je Schlüssel; 50 MB je Datei; keine Idempotenz | ergänzt; Anbindung folgt |
| Persistenter Ereigniseingang mit HMAC-Prüfung | – | nicht nötig: API-Werk meldet nicht per Webhook, Ergebnisse werden abgefragt |
| Nachrichten-Outbox | – | vorerst nicht nötig; Benachrichtigungen über die Warteschlange |

Redis wird nicht eingesetzt: Warteschlange, Cache und Sessions laufen über die Datenbank.

## 3. Sicherheit

| Baustein | Umsetzung | Vergleich zur Referenz |
|---|---|---|
| Anmeldung | Fortify, serverseitige Sitzungen; keine Selbstregistrierung | gleich |
| Rollen und Rechte | Spatie laravel-permission | gleich |
| 2FA | TOTP über Fortify (intern Google2FA), Wiederherstellungscodes | gleich; Pflicht für alle noch offen |
| Passkeys | WebAuthn über Fortify | ergänzt |
| API-Authentifizierung | – | Sanctum vorerst nicht nötig (keine eigene API) |
| Verschlüsselung sensibler Werte | Verschlüsselte Casts, u. a. für Zugangsdaten der KI-API | gleich |
| Transport | HTTPS/TLS | gleich |
| Formularschutz | CSRF, serverseitige Validierung | gleich |
| Protokollierung | Verwaltungsaktionen (Upload, Rechte, Freigaben) und technische Logs | gleich |
| Geheimnisse im Code | gitleaks als Pre-Commit-Hook | ergänzt |
| Keine externen Ressourcen | Test prüft alle Seiten auf fremde Hosts | ergänzt (Vorgabe „alles lokal“) |

Rechte werden an den Zugriffswegen und an den auslösenden Aktionen geprüft, zusätzlich bei
Suchtreffern (vor dem Reranking) und bevor Inhalte an ein Sprachmodell gehen. Dokumentinhalte
sind für das Sprachmodell Daten, keine Anweisungen. Keine Authorization-Köpfe, ganzen Dokumente
oder Prompts in technischen Logs.

## 4. Entwicklung und Qualität

| Baustein | Umsetzung | Vergleich zur Referenz |
|---|---|---|
| Lokale Umgebung | Laravel Sail (Docker in WSL2): PHP 8.5, MySQL 8.4, Meilisearch, Mailpit | ergänzt |
| Tests | Pest 4 auf PHPUnit 12; Tests im PHPUnit-Klassenstil | gleich (Runner ergänzt) |
| Code-Stil | Laravel Pint | gleich |
| Statische Analyse | PHPStan/Larastan Stufe 7 | ergänzt |
| Versionsverwaltung | Git, Gitea (lokal führend, Gitea von ITM als Push-Mirror) | gleich |

## 5. Betrieb (Produktion, geplant)

Übernommen aus der Referenz: Linux-Server, Nginx, PHP-FPM, Worker unter systemd, Cron für den
Scheduler, Bereitstellungsablauf (Abhängigkeiten, Assets, Migrationen, Caches, Dienste neu laden,
Prüfung), Lebenszeichen von Worker und Scheduler, Überwachung fehlgeschlagener und überfälliger
Jobs. Meilisearch läuft als eigener systemd-Dienst. Sail dient nur der Entwicklung; Versionen von
PHP, MySQL und Meilisearch sind in Entwicklung und Produktion gleich.

Ergänzt bzw. anders als in der Referenz:

- **Externe Alarmierung von Anfang an** (z. B. Mail), wenn Worker oder Scheduler ausfallen,
  Jobs fehlschlagen oder die KI-API ITM nicht erreichbar ist.
- **Backups verschlüsselt**, bevor sie den Server verlassen (z. B. restic). Speicherort,
  Aufbewahrungsdauer und Zuständigkeit sind noch offen. Gesichert werden Datenbank, private Uploads und
  Konfiguration; der Meilisearch-Index nicht, er wird aus MySQL neu aufgebaut.
- **Wiederanlauf auf einem Ersatzserver** einmal vollständig testen; Datenverlust und
  Wiederanlaufzeit mit BauIn und ITM festlegen.

## 6. Bewusste Abweichungen von der Referenz

| Thema | Referenz | KI-BauIN | Begründung |
|---|---|---|---|
| Livewire | 3 | 4 | Neues Projekt; das Starter-Kit von Laravel 13 baut auf Livewire 4 auf, ein späterer Umstieg entfällt. |
| TallStackUI | 3 | 4 | TallStackUI 3 läuft nur mit Livewire 3; Version 4 setzt Livewire ≥ 4.3 voraus. |
| PHP | 8.4 | 8.5 | Sicherheitsupdates bis Ende 2029 statt Ende 2028. |
| Backups | unverschlüsselt, Hetzner Object Storage | verschlüsselt, Ort noch offen | Vertrauliche Vertragsunterlagen; Vorgabe „alles lokal“. |
| Suche | – | Meilisearch | Hybride Suche und Vektorsuche für die Nachtragsprüfung. |

## 7. Offene Punkte

- Ist 2FA für alle Benutzer Pflicht?
- Verlangen BauIn oder ITM eine Festplattenverschlüsselung auf den Servern bei ITM?
- Backups: Speicherort, Aufbewahrungsdauer und wer dafür zuständig ist.
- Weitere Sprachen über Deutsch und Englisch hinaus (technisch vorbereitet, fachlich nicht angefragt).
- Datenschutz der KI-API: Standort von API-Werk und KI-Server, Auftragsverarbeitung, Aufbewahrung
  hochgeladener Dokumente und Ergebnisse.
- Anmeldung mit eigenem Passwort und 2FA oder mit dem Microsoft-Konto von BauIn.

## Architekturübersicht

```mermaid
flowchart LR
    Browser[Oberfläche] --> Nginx[Nginx / HTTPS]
    Nginx --> PHP[PHP-FPM]
    PHP --> App[Laravel / Livewire / Services]
    App --> DB[(MySQL)]
    App --> Files[Privater Dateispeicher]
    App --> Search[(Meilisearch)]
    App --> Queue[Datenbank-Warteschlange]
    Queue --> Worker[Worker unter systemd]
    Worker --> KI[KI-API ITM über API-Werk: OCR, Embeddings, Reranker, Sprachmodell]
    Worker --> DB
    Worker --> Search
    Cron[Cron] --> Scheduler[Laravel Scheduler]
    Scheduler --> Queue
    Health[Statusprüfung und Alarmierung] --> Worker
    Health --> Scheduler
    Backup[Verschlüsselte Sicherung] --> Storage[Speicherort noch offen]
```