# 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, unprivilegiert empfohlen | 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.

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

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

## 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