updated skeleton with true data

DEV_SETUP.md

@@ -1,2 +1,288 @@
-# Dev Setup
-Full setup guide.
+# Developer Setup Guide
+
+Dieses Dokument befähigt jeden Entwickler dazu, das komplette XTTS2-TTS-System lokal aufzusetzen, zu verstehen, zu debuggen und zu erweitern – ohne Rückfragen.
+
+---
+
+# 1. Ziel des Dokuments
+
+* Lokale Entwicklungsumgebung vollständig einrichten
+* Services starten & stoppen
+* Worker skalieren
+* API testen
+* Debugging-Strategien
+* Best Practices für Code, Deployment & GPU-Nutzung
+
+---
+
+# 2. Voraussetzungen
+
+## Software
+
+* Docker ≥ 24.x
+* Docker Compose ≥ v2.x
+* Git
+* Python 3.10–3.11
+* Optional: Editor wie VS Code mit Python- & Docker-Extensions
+
+## Hardware
+
+* Linux (empfohlen), macOS oder Windows WSL2
+* Für GPU-Betrieb: NVIDIA GPU + Container Toolkit
+
+GPU prüfen:
+
+```bash
+nvidia-smi
+```
+
+NVIDIA Docker prüfen:
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.1.0-base nvidia-smi
+```
+
+---
+
+# 3. Repository klonen
+
+```bash
+git clone <repo-url>
+cd tts-server
+```
+
+---
+
+# 4. Projektstruktur
+
+```
+tts-server/
+├── gateway/                → FastAPI-Gateway
+│   ├── main.py
+│   ├── api/
+│   ├── core/
+│   ├── voices/
+│   ├── logs/
+│   └── Dockerfile
+│
+├── worker/                 → XTTS2 Worker
+│   ├── main.py
+│   ├── engine/
+│   ├── core/
+│   └── Dockerfile
+│
+├── scripts/
+│   └── find_port.py        → Portscanner (8000–8100)
+│
+├── docker-compose.yml      → Multi-Service Orchestration
+├── Makefile                → PRO Workflow
+├── README.md
+└── ONBOARDING.md
+```
+
+---
+
+# 5. Docker-basiertes Development (empfohlen)
+
+## 5.1 Images bauen
+
+```bash
+make build
+```
+
+## 5.2 Server starten
+
+```bash
+make up
+```
+
+Der Portscanner wählt automatisch den ersten freien Port (8000–8100) und legt ihn ab in:
+
+```
+gateway/port.txt
+gateway/logs/gateway.log
+```
+
+## 5.3 Logs ansehen
+
+```bash
+make logs
+```
+
+## 5.4 Services stoppen
+
+```bash
+make down
+```
+
+## 5.5 Status anzeigen
+
+```bash
+make status
+```
+
+---
+
+# 6. Ohne Docker entwickeln (lokales Debugging)
+
+## 6.1 Virtuelle Umgebung
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+## 6.2 Abhängigkeiten installieren
+
+Gateway:
+
+```bash
+pip install -r gateway/requirements.gateway.txt
+```
+
+Worker:
+
+```bash
+pip install -r worker/requirements.worker.txt
+```
+
+Redis lokal starten:
+
+```bash
+docker run -p 6379:6379 redis:7
+```
+
+Gateway starten:
+
+```bash
+python gateway/main.py
+```
+
+Worker starten:
+
+```bash
+python worker/main.py
+```
+
+---
+
+# 7. TTS API testen
+
+## 7.1 Healthcheck
+
+```bash
+curl http://localhost:<PORT>/health
+```
+
+## 7.2 TTS Anfrage
+
+```bash
+curl -X POST http://localhost:<PORT>/v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+        "model": "xtts-v2",
+        "input": "Das ist ein Test.",
+        "voice": "auto",
+        "format": "wav"
+      }' \
+  --output test.wav
+```
+
+## 7.3 Stimme registrieren
+
+```bash
+curl -X POST http://localhost:<PORT>/v1/voices/register \
+  -H "Content-Type: application/json" \
+  -d '{
+        "name": "german_narrator",
+        "samples": ["https://example.com/sample.wav"]
+      }'
+```
+
+---
+
+# 8. Worker skalieren
+
+Höhere Last? Mehrere Worker starten:
+
+```bash
+make worker-scale N=4
+```
+
+Redis verteilt Jobs automatisch FIFO.
+
+---
+
+# 9. Selftest
+
+```bash
+make selftest
+```
+
+Testet:
+
+* Redis erreichbar
+* Gateway online
+* Worker zieht Jobs
+* Synthese funktioniert
+
+---
+
+# 10. Debugging
+
+## Gateway startet nicht
+
+* Prüfen: `gateway/logs/`
+* Port frei? `gateway/port.txt`
+* Redis erreichbar?
+
+## Worker lädt nicht
+
+* XTTS2 Modell verfügbar?
+* GPU verfügbar? `nvidia-smi`
+* Torch CUDA Version kompatibel?
+
+## Audio-Probleme
+
+* Voice Sample ungeeignet
+* Sprache nicht angegeben
+* Format falsch
+
+---
+
+# 11. Code Guidelines
+
+* PEP8 Stil
+* Logging strukturiert (JSON empfohlen)
+* Kein Hardcoding von Pfaden
+* Hohe Modularität
+* Unit Tests für Kernkomponenten
+* Feature Branches: `feature/<name>`
+* Commits: Conventional Commits
+
+---
+
+# 12. Best Practices
+
+* Worker lieber horizontal skalieren statt optimieren
+* Keine sensiblen Voice Samples committen
+* Docker Images regelmäßig aktualisieren
+* Für Public Deployments: Auth Layer aktivieren
+
+---
+
+# 13. Nächste Schritte für Entwickler
+
+* Monitoring & Dashboards
+* WebSocket Realtime TTS
+* Mehrsprachige Voice Registry
+* Model Hot-Swapping (XTTS2, F5, Kokoro)
+* CI/CD Pipeline hinzufügen
+
+---
+
+# 14. Fertig!
+
+Wenn du dieses Dokument verstanden hast, kannst du das Projekt vollständig entwickeln, erweitern und deployen.
+
+Viel Erfolg! 🚀