updated skeleton with true data

ONBOARDING.md

@@ -1,2 +1,270 @@
-# Onboarding
-Full onboarding.
+# Onboarding Guide
+
+Willkommen im Projekt! Dieses Dokument führt neue Entwickler vollständig ein – ohne Rückfragen, ohne offene Punkte.
+
+Ziel: Du sollst in der Lage sein, das gesamte System zu verstehen, zu betreiben und weiterzuentwickeln.
+
+---
+
+# 1. Projektüberblick
+
+Das XTTS2 TTS-System ist eine modulare, verteilte Plattform für hochwertige Text-to-Speech-Synthese mit Zero-Shot Voice Cloning. Der Aufbau orientiert sich an professionellen Backend-Architekturen mit Queueing, GPU-Workern und einer OpenAI-kompatiblen API.
+
+**Hauptkomponenten:**
+
+* **Gateway** (FastAPI): HTTP-API, Validierung, Routing, Port-Autodetection.
+* **Redis**: Queue, Cache, interne Metadaten.
+* **Worker** (XTTS2): führt TTS aus, nutzt GPU automatisch, arbeitet skalierbar.
+
+Dieses System eignet sich für:
+
+* Spielevertonung
+* Automatisiertes Voice-Over
+* Lokale AI-Pipelines
+* Multimodale Agenten
+
+---
+
+# 2. Architektur
+
+```
+Client → Gateway → Redis Queue → Worker (XTTS2) → Gateway → Client
+```
+
+* Das **Gateway** nimmt Requests entgegen und legt Jobs in Redis ab.
+* **Worker** verarbeiten Jobs parallel und liefern Audiodaten zurück.
+* Die API ist **OpenAI-kompatibel** – Clients können ohne Anpassung migriert werden.
+
+---
+
+# 3. Voraussetzungen
+
+## Software
+
+* Docker & Docker Compose
+* Git
+* Python 3.10 / 3.11 (für lokales Debugging)
+* NVIDIA GPU + Container Toolkit (optional, aber empfohlen)
+
+## Hardware
+
+* 8 GB RAM minimum
+* GPU mit mindestens 4–6 GB VRAM für XTTS2
+
+---
+
+# 4. Repository klonen
+
+```bash
+git clone <repo-url>
+cd tts-server
+```
+
+---
+
+# 5. Projektstruktur verstehen
+
+```
+gateway/      → FastAPI-Gateway
+worker/       → XTTS2-GPU-Worker
+scripts/      → Hilfsskripte (Portfinder, Selftest)
+voices/       → Voice Registry
+Makefile      → Build-, Deploy- und Diagnosewerkzeuge
+docker-compose.yml
+```
+
+Die wichtigsten Einstiegspunkte:
+
+* `gateway/main.py` – Start des API-Gateways
+* `worker/main.py` – Start des XTTS2-Workers
+* `scripts/find_port.py` – Portscanner (8000–8100)
+
+---
+
+# 6. System starten
+
+```bash
+make build
+make up
+```
+
+* Der Portscanner prüft Ports 8000–8100
+* Der freie Port wird in `gateway/port.txt` gespeichert
+
+Status prüfen:
+
+```bash
+make status
+```
+
+Stoppen:
+
+```bash
+make down
+```
+
+---
+
+# 7. API testen
+
+## Healthcheck
+
+```bash
+curl http://localhost:<PORT>/health
+```
+
+## TTS Request
+
+```bash
+curl -X POST http://localhost:<PORT>/v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+        "model": "xtts-v2",
+        "input": "Hello there!",
+        "voice": "auto",
+        "format": "wav"
+      }' \
+  --output output.wav
+```
+
+## Stimme registrieren
+
+```bash
+curl -X POST http://localhost:<PORT>/v1/voices/register \
+  -H "Content-Type: application/json" \
+  -d '{
+        "name": "narrator",
+        "samples": ["https://example.com/voice.wav"]
+      }'
+```
+
+---
+
+# 8. Entwicklung
+
+## Lokales Setup ohne Docker
+
+### Virtualenv
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Abhängigkeiten installieren
+
+Gateway:
+
+```bash
+pip install -r gateway/requirements.gateway.txt
+```
+
+Worker:
+
+```bash
+pip install -r worker/requirements.worker.txt
+```
+
+### Services starten
+
+Redis (Lokal):
+
+```bash
+docker run -p 6379:6379 redis:7
+```
+
+Gateway:
+
+```bash
+python gateway/main.py
+```
+
+Worker:
+
+```bash
+python worker/main.py
+```
+
+---
+
+# 9. Skalieren
+
+Mehrere Worker starten:
+
+```bash
+make worker-scale N=3
+```
+
+Der Gateway verteilt automatisch die Jobs über Redis.
+
+---
+
+# 10. Selftest
+
+```bash
+make selftest
+```
+
+Prüft:
+
+* Redis erreichbar
+* Worker verarbeitet Jobs
+* Audioausgabe funktioniert
+
+---
+
+# 11. Troubleshooting
+
+## Gateway startet nicht?
+
+* Port belegt → `gateway/port.txt` prüfen
+* Logs prüfen → `gateway/logs/`
+* Redis erreichbar?
+
+## Worker reagiert nicht?
+
+* GPU verfügbar? → `nvidia-smi`
+* Torch kompatibel?
+* XTTS2 Modell lädt?
+
+## Audio klingt falsch?
+
+* Voice-Sample ungeeignet
+* Format falsch gesetzt
+* Sprache nicht angegeben
+
+---
+
+# 12. Best Practices
+
+* Keine persönlichen Sprachsamples committen
+* Docker Images regelmäßig erneuern
+* Worker skalieren statt Gateway ändern
+* API-Versionen strikt pflegen
+* Code Style: PEP8
+
+---
+
+# 13. Weiterentwicklung
+
+Empfohlene nächste Schritte:
+
+* Monitoring (Prometheus)
+* WebSocket TTS
+* Multi-Model Routing
+* GUI für Voice Management
+* Auth Layer für öffentliche Deployments
+
+---
+
+# 14. Verantwortlichkeiten
+
+* Projektleitung: Stephan W.
+* Backend Architektur: Team
+  evtl. weitere Rollen später definieren
+
+---
+
+# 15. Abschluss
+
+Wenn du bis hier gelesen hast, bist du vollständig einsatzfähig. Viel Erfolg!“}