# Architektur

## Ziel

Die Plattform stellt eine private, lokal betriebene OpenAI-kompatible API
bereit. Jede Komponente hat genau eine Aufgabe und kann unabhängig ersetzt
werden. Ein Neuaufbau darf keine Dateien vom alten Host voraussetzen, die nicht
in diesem Repository oder im Modellmanifest beschrieben sind.

## Komponenten

| Komponente | Port | Ausführung | Aufgabe |
|---|---:|---|---|
| AI Profile Router | 8081 | systemd, gehärtet | zentrale Client-API und Orchestrierung |
| llama.cpp | 8080 | systemd | Textmodell, Tool Calling und MCP |
| Whisper | 8084, nur localhost | systemd | Speech-to-Text |
| XTTS | 8085, nur localhost | systemd | Text-to-Speech |
| TinySearch | 8000, nur localhost | Docker | kompakte Websuche |
| SearXNG | intern | Docker | Suchmaschinen-Metasuche |
| LLama-GUI | 5240, optional | systemd | manuelle Administration |
| Glances | lokal, optional | systemd | Systemmetriken |

## Request-Fluss

1. Ein Client verwendet ausschließlich Port 8081.
2. Der Router veröffentlicht `qwen-fast`, `qwen-medium` und `qwen-long`.
3. Passt das aktive Profil nicht zum virtuellen Modell, wird llama.cpp kontrolliert
   mit dem passenden Profil neu gestartet.
4. Der Router wartet auf Modellname und erwartete Kontextgröße.
5. Erst dann wird die Anfrage an Port 8080 weitergeleitet.

Profilwahl und Weiterleitung bilden dabei eine atomare Modell-Lease. Ein
zweiter Request kann das Profil nicht mehr zwischen Auswahl und Inferenz
wechseln. Laufende Requests werden vor einem GPU-Hotswap vollständig beendet;
bei Überschreiten des Drain-Timeouts wird der Wechsel abgebrochen, nicht der
Chat.

## Profilprinzip

Die Profile sind vollständige systemd-Overrides. Ein Profilwechsel kopiert die
gewählte Datei atomar auf `override.conf`, lädt systemd neu und startet genau
einen llama.cpp-Dienst neu. Es gibt niemals mehrere Textmodelle gleichzeitig.
Das unabhängige Register `/etc/mike-ai/router-profiles.json` definiert Kontext
und erwarteten Modellalias. Readiness gilt nur, wenn beides exakt passt; eine
abweichende oder fehlende Registry verhindert den Start.

## GPU-Hotswap

Vision und Bildgenerierung teilen sich die RTX mit dem Textmodell. Der Router:

1. sperrt die GPU-Orchestrierung,
2. merkt sich das aktive Textprofil,
3. stoppt llama.cpp,
4. startet vorübergehend Vision oder FLUX,
5. beendet den Hilfsprozess vollständig,
6. stellt das ursprüngliche Textprofil wieder her,
7. prüft Modell und Kontext vor der Freigabe.

Der zuletzt stabile Zustand und temporäre Worker-PIDs werden atomar unter
`/var/lib/mike-ai-profile-router/state.json` festgehalten. Beim Routerstart
werden ausschließlich dort erfasste Prozesse nach zusätzlicher
Kommandozeilenprüfung beendet und das letzte Profil wiederhergestellt.

## Vertrauensgrenzen

- Port 8081 verlangt einen eigenen API-Key; nur `/health` und `/ready` sind
  absichtlich anonym und enthalten keine privaten Daten.
- Der Client-Key wird vor dem lokalen Upstream entfernt.
- Bild-Uploads sind begrenzt. Remote-Bild-URLs sind standardmäßig aus, damit
  der Vision-Pfad nicht als Zugriff auf Intranet oder Metadatenendpunkte dient.
- Maximal 16 Requests werden gleichzeitig bearbeitet; weitere erhalten 429.
- Der Dienst benötigt derzeit wegen systemd-Profilwechsel und GPU-Hotswap noch
  Root-Rechte. Die systemd-Sandbox begrenzt diese, ersetzt aber keine künftige
  Aufteilung in unprivilegierten Proxy und eng begrenzten Root-Helper.

## Verzeichnislayout auf dem Zielhost

```text
/opt/mike-ai/
  ai-profile-router/     Routercode und eigenes Venv
  llama.cpp/             exakt ein produktiver Build
  models/                Modelle nach Manifest
  whisper.cpp/           Speech-to-Text Runtime
  xtts/                  XTTS Runtime und Cache
  web-search/            Docker Compose für TinySearch/SearXNG

/etc/mike-ai/
  mcp-servers.json       lokale, geheime produktive Konfiguration
  *.env                  Credentials, niemals im Git

/etc/systemd/system/
  mike-ai-*.service
  mike-ai-llama-ui.service.d/
    override.conf
    profile-fast.conf.disabled
    profile-medium.conf.disabled
    profile-long.conf.disabled
```

## Nicht Teil der Zielarchitektur

- parallele llama.cpp-Builds
- allgemeiner Shell-MCP im Standardprofil
- doppelte Unraid-MCPs
- RX-spezifische Dienste ohne eingebaute RX
- automatisch startende Benchmark-Dienste
- Modellkopien außerhalb des dokumentierten Modellverzeichnisses