BauIN/docs/tech-stack.md

KI-BauIN – Tech-Stack

Stand: 1. 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 (OCR, Embeddings, Reranker, ggf. Sprachmodell), Projektleitung und abrechnende Firma. Stellt auch die Server (Staging, Produktion) und den Gitea, auf den das Repository gespiegelt wird.
• BauIn: Endkunde. Liefert Fachdaten (LVs, MKAs, 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
PhpSpreadsheet	Excel-Export der Bewertungsmatrix	geplant, sobald die Vorlage vorliegt
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	OCR, Embeddings (Qwen3-Embedding-8B), Reranker, ggf. Sprachmodell	ergänzt; Anbindung folgt
Persistenter Ereigniseingang mit HMAC-Prüfung	Falls die KI-API Ergebnisse per Webhook meldet	geplant, abhängig von der API
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 und bevor Inhalte an ein Sprachmodell gehen.

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).

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: OCR, Embeddings, Reranker]
    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]