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.

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
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 des Kunden	OCR, Embeddings (Qwen3-Embedding-8B), Reranker	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, Kunde 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 nicht erreichbar ist.
• Backups verschlüsselt, bevor sie den Server verlassen (z. B. restic). Speicherort und Aufbewahrungsdauer legt der Kunde fest. 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 dem Kunden 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 nach Vorgabe des Kunden	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?
• Verlangt die IT des Kunden eine Festplattenverschlüsselung auf der VM?
• Speicherort und Aufbewahrungsdauer der Backups.
• Deutsche Übersetzung der Oberflächentexte (das Starter-Kit liefert englische Texte).

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 des Kunden: 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 nach Vorgabe des Kunden]