BauIN/docs/tech-stack.md

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, 2FA, Passkeys; ohne E-Mail-Funktionen (keine E-Mails laut BauIn)	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	Stellungnahme aus Word-Vorlage (nur .docx)	Phase 2
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; zunächst freiwillig, später Pflicht per Schalter
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
Schlüssel der KI-API	Nie in .env: verschlüsselt in der Datenbank, in der Oberfläche nur beschreibbar; in der Entwicklung Schlüssel-Proxy mit Windows-Anmeldeinformationsverwaltung (tools/ki-proxy)	ergänzt
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, eigene Regel für API-Werk-Schlüssel (.gitleaks.toml)	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; Push-Mirror nach https://gitea.itm-technologies.de/ChristophGraf/BauIN)	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, wenn Worker oder Scheduler ausfallen, Jobs fehlschlagen oder die KI-API ITM nicht erreichbar ist. Die Anwendung verschickt keine E-Mails; der Weg wird mit ITM abgestimmt (AP11, E11.3).
• 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

Vor dem Livegang zu klären (Liste in docs/plaene/AP11-betrieb.md): Zugriff, Adresse, Backups, Datenschutz und Informationssicherheit, Einschalten der 2FA-Pflicht. Server, Verschlüsselung und Datenverarbeitung bei API-Werk sind Sache von ITM.

• Weitere Sprachen über Deutsch und Englisch hinaus (technisch vorbereitet, fachlich nicht angefragt).

Geklärt am 05.10.: eigenes Passwort statt Microsoft-Konto, 2FA zunächst freiwillig und später Pflicht, keine E-Mails, nur Schlüssel für die Produktion.

Architekturübersicht

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]