From 5f0e6a2b7967f5c7f3a102aee26dcac349941419 Mon Sep 17 00:00:00 2001
From: ghost <ma-koenig@gmx.net>
Date: Thu, 30 Oct 2025 19:07:33 +0100
Subject: [PATCH] Add initial voice channel docs

---
 docs/architecture/signaling_flow.md | 24 ++++++++++++++++++++++++
 docs/components/call_controls.md    | 25 +++++++++++++++++++++++++
 docs/components/connection_panel.md | 24 ++++++++++++++++++++++++
 docs/components/status_display.md   | 13 +++++++++++++
 docs/config/config_management.md    | 23 +++++++++++++++++++++++
 docs/index.md                       | 18 ++++++++++++++++++
 docs/utils/media_manager.md         | 22 ++++++++++++++++++++++
 7 files changed, 149 insertions(+)
 create mode 100644 docs/architecture/signaling_flow.md
 create mode 100644 docs/components/call_controls.md
 create mode 100644 docs/components/connection_panel.md
 create mode 100644 docs/components/status_display.md
 create mode 100644 docs/config/config_management.md
 create mode 100644 docs/index.md
 create mode 100644 docs/utils/media_manager.md

diff --git a/docs/architecture/signaling_flow.md b/docs/architecture/signaling_flow.md
new file mode 100644
index 0000000..8071438
--- /dev/null
+++ b/docs/architecture/signaling_flow.md
@@ -0,0 +1,24 @@
+# Signaling & Media Flow
+
+Dieses Dokument beschreibt, wie das Voice-Channel-Modul mit Signaling-Server (`niom-signaling`) und TURN-Server (`niom-turn`) interagiert.
+
+## Beteiligte Dienste
+- **Client (`niom-webrtc`)**: Dioxus-Frontend im Browser. Baut PeerConnections, verwaltet UI-Zustand und kommuniziert mit Signaling per WebSocket.
+- **Signaling (`niom-signaling`)**: Actix-Web-Server, der Nachrichten zwischen Peers austauscht. Derzeit Broadcast, später rooms.
+- **TURN (`niom-turn`)**: UDP/TLS TURN-Server mit STUN-Fallback. Sorgt für NAT-Traversal, sobald ICE-Candidates verwendet werden.
+
+## Flow (MVP Heutiger Stand)
+1. **WebSocket-Aufbau**: `ConnectionPanel` verbindet sich zu `ws://localhost:3478/ws`.
+2. **Peer-ID**: Clients generieren lokale IDs; Remote-ID wird manuell eingetragen.
+3. **Offer/Answer**:
+   - Initiator (`CallControls`) baut `RtcPeerConnection`, hängt lokale Audio-Tracks an und erzeugt ein Offer (SDP).
+   - Offer wird via Signaling an Remote gesendet.
+   - Responder (`ConnectionPanel` Coroutine) erstellt eigene PeerConnection und generiert eine Answer.
+4. **ICE-Kandidaten**: Beide PeerConnections senden `candidate`-Messages an Signaling. Kandidaten werden dynamisch hinzugefügt.
+5. **Medien**: `ontrack`-Handler erzeugt `<audio>`-Elemente und spielt Remote-Audio automatisch ab.
+
+## Geplante Erweiterungen
+- **Room-/Channel-IDs** statt manueller Remote-ID.
+- **Persistentes State-Management**: Gemeinsame Signals/Store für Teilnehmerliste, Sprecherstatus, Device-Einstellungen.
+- **TURN-Integration**: Konfigurierbare ICE-Server aus `appsettings.json` (STUN/TURN). UI-Feedback bei Verbindungspfaden.
+- **Video-Support**: Erweiterung der MediaStreams für Video, Layout-Anpassungen.
diff --git a/docs/components/call_controls.md b/docs/components/call_controls.md
new file mode 100644
index 0000000..a4c1859
--- /dev/null
+++ b/docs/components/call_controls.md
@@ -0,0 +1,25 @@
+# CallControls Component
+
+## Zweck
+- Steuert Anrufstart als Initiator, Mikrofonberechtigungen und Mute/Ende-Interaktionen.
+
+## Kernfunktionen
+- `request_microphone_access()`: nutzt `MediaManager` zum Einholen des MediaStreams und speichert ihn in `local_media` Signal.
+- `create_offer()`: Erstellt und sendet Offer via Signaling, registriert `onicecandidate` & `ontrack`.
+- `mute / end`: Lokalen Zustand aktualisieren, PeerConnection schließen.
+
+## Signalübersicht
+- `mic_granted`, `audio_muted`, `in_call`: UI States.
+- Teilt `peer_id`, `remote_id`, `connected`, `websocket`, `peer_connection` (Initiator), `local_media` mit anderen Komponenten.
+
+## Workflow
+1. **Mikrofon freigeben** → Tracks werden zur PeerConnection hinzugefügt.
+2. **Anruf starten** → PeerConnection erzeugen, Offer senden, auf Answer warten.
+3. **Mute/Unmute** → Aktuell nur UI-State, TODO: Track-`enabled` toggeln.
+4. **Anruf beenden** → PeerConnection schließen, Signals resetten.
+
+## TODOs
+- Realer Mute/Unmute über `MediaStreamTrack.enabled`.
+- Visuelle Feedback-Elemente (Button-States im Discord-Stil).
+- Device-Auswahl (Audio Output/Input) vor dem Start.
+- Error-Toasts (z. B. wenn Offer scheitert).
diff --git a/docs/components/connection_panel.md b/docs/components/connection_panel.md
new file mode 100644
index 0000000..a3ffc97
--- /dev/null
+++ b/docs/components/connection_panel.md
@@ -0,0 +1,24 @@
+# ConnectionPanel Component
+
+## Zweck
+- Stellt Verbindungsstatus dar (WebSocket, Mikrofon) und nimmt Remote-Peer-ID entgegen.
+- Hält Signals für Peer-Verbindung als **Responder** und verwaltet Offer/Answer-Eingang.
+
+## Wichtige Signals
+- `peer_id`, `remote_id`, `connected`, `websocket`
+- `peer_connection`: Responder `RtcPeerConnection`
+- `initiator_connection`: Referenz auf Initiator-PC (für Answer/Renegotiation)
+- `local_media`: geteilter `MediaStream`
+
+## Ablauf
+1. **Peer-ID generieren** (`use_effect` mit Timestamp + Random).
+2. **WebSocket verbinden** (`ws://localhost:3478/ws`): setzt `onopen/onclose/onmessage` Handler.
+3. **Offer-Coroutine** (`use_coroutine`): empfängt `SignalingMessage` vom Typ `offer`, baut PeerConnection (Responder) und sendet Answer.
+4. **ICE-Kandidaten**: `onicecandidate` sendet Kandidaten zurück; empfangene Kandidaten werden an vorhandene PCs angehängt.
+5. **Audio-Wiedergabe**: `ontrack` erstellt `<audio>` Element und setzt `srcObject`.
+
+## Geplante Verbesserungen
+- Room-basierte IDs statt manueller Eingabe.
+- UI-Feedback bei kopierter Peer-ID (Clipboard API).
+- Mehr Statusanzeigen (ICE connected, TURN usage).
+- Fehler-Handling für WebSocket-Disconnects mit Auto-Reconnect.
diff --git a/docs/components/status_display.md b/docs/components/status_display.md
new file mode 100644
index 0000000..a2b9a60
--- /dev/null
+++ b/docs/components/status_display.md
@@ -0,0 +1,13 @@
+# StatusDisplay Component
+
+## Zweck
+- Einfache Übersicht über Systemzustand (Placeholder für spätere KPIs wie Mitglieder, Ping, aktive Sprecher).
+
+## Aktueller Stand
+- Zeigt statisch "System Stabil" und `connected` Status (WebSocket).
+- TODO: WebRTC-Status placeholder.
+
+## Ausbauideen
+- Anzeigen von: ICE-Verbindungstyp (relay/srflx), Packet Loss, Latenz.
+- Integrationen für Audiopegel, Sprecherkennung, Channel-Mitgliederliste.
+- Nutzung von Icons/Badges im Discord-Stil.
diff --git a/docs/config/config_management.md b/docs/config/config_management.md
new file mode 100644
index 0000000..823d271
--- /dev/null
+++ b/docs/config/config_management.md
@@ -0,0 +1,23 @@
+# Konfigurations-Management
+
+## Dateistruktur
+- `appsettings.example.json`: Beispielkonfiguration für lokale Entwicklung.
+- `appsettings.json`: Wird zur Laufzeit gelesen. Im Browser kann die Config über ein `<script id="app-config">` Element injiziert werden.
+
+## Strukturen
+```
+Config {
+    server: ServerOptions {
+        stun_server: String,
+    }
+}
+```
+
+## Loader
+- `load_config_sync_or_default()`: Wird synchron aufgerufen, bevorzugt HTML-Injektion (WASM) bzw. `appsettings.json` (native). Fallback: Google STUN.
+- `load_config_or_default().await`: Async Loader (`gloo-net` in WASM / Datei aufzwingen in native Builds).
+
+## Nächste Schritte
+- Mehrere ICE-Server (STUN/TURN) unterstützen.
+- Konfiguration für Signaling-URL und Channel-Metadaten.
+- Feature-Flags für Voice/Video, Logging-Level, Devtools.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..3dbb8bb
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,18 @@
+# niom-webrtc Voice Channel Module Docs
+
+Diese Dokumentationssammlung beschreibt das MVP-Modul "Voice Channel" im Projekt `niom-webrtc`. Die Struktur spiegelt die wichtigsten Programmkomponenten wider und soll als Einstieg für neue Sessions dienen.
+
+- [`architecture/signaling_flow.md`](architecture/signaling_flow.md) – High-Level-Ablauf von Signaling, WebRTC und TURN.
+- [`config/config_management.md`](config/config_management.md) – Konfigurationen und Defaults (STUN/TURN, Appsettings).
+- [`components/`](components/) – UI-Komponenten (Discord-Voice-Channel UI) inkl. Zustandsfluss.
+- [`utils/media_manager.md`](utils/media_manager.md) – Medien- und Peer-Connection-Helfer.
+
+## Aktueller Fokus
+- Discord-Voice-Channel UI als reines Modul ohne restliche App-Shell.
+- Saubere Trennung von Initiator/Responder-Logik.
+- Testbarkeit im Browser (WASM) und auf CLI-Ebene.
+
+## Offene ToDos (Stand 30.10.2025)
+- UI auf Discord-Optik bringen (Layouts, States, Device-Auswahl).
+- Signaling-Protokoll für Räume/Teilnehmer verfeinern.
+- WebRTC-Lifecycle vereinfachen (Hooks/State-Store).
diff --git a/docs/utils/media_manager.md b/docs/utils/media_manager.md
new file mode 100644
index 0000000..ea4ee2d
--- /dev/null
+++ b/docs/utils/media_manager.md
@@ -0,0 +1,22 @@
+# MediaManager Utility
+
+## Aufgaben
+- Kapselt WebRTC-/Media-APIs (`RtcPeerConnection`, `MediaStream`).
+- Stellt Hilfsmethoden bereit für Offer/Answer, ICE-Kandidaten und Mikrofonzugriff.
+
+## Hauptmethoden
+- `create_peer_connection()` → Erstellt `RtcPeerConnection` mit Default-STUN.
+- `create_offer(pc)` / `handle_offer(pc, sdp)` / `handle_answer(pc, sdp)` → Asynchrone SDP-Verarbeitung.
+- `request_microphone_access()` → Lädt Audio-Stream via `navigator.mediaDevices.getUserMedia`.
+- `add_stream_to_pc(pc, stream)` → Fügt Tracks via dynamischem `addTrack` hinzu.
+- `add_ice_candidate(pc, candidate_json)` → Parsed JSON und ruft `addIceCandidate`.
+- `stop_stream()` → Stoppt aktive Tracks.
+
+## Zustandsverwaltung
+- `state: MediaState` (enum `Uninitialized`, `Requesting`, `Granted`, `Denied`, `NotSupported`). Dient für UI-Feedback.
+
+## TODOs
+- Mehrere ICE-Server aus Config berücksichtigen.
+- Fehlerbehandlung vereinheitlichen (eigene Error-Typen, Logging).
+- Audio-Level-Monitoring (AnalyserNode) einbauen.
+- Video-Streams unterstützen (getUserMedia-Constraints).