Expand router into reproducible local AI platform

docs/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# 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