docs: komplette CallRec-Dokumentation mit Mermaid-Diagrammen

Architektur, Hardware/Thermik, PipeWire-Audio-Topologie, Aufnahme-Pipeline, Diarization (Anchor-Merge), LLM-Analyse (Gemma-3-4B/NPU), iPhone-BT-HFP, Betrieb/Troubleshooting und Changelog-Chronik. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 10:51:22 +02:00
commit db3d946592
9 changed files with 657 additions and 0 deletions
@@ -0,0 +1,61 @@
+# CallRec — Dokumentation
+
+Selbst gehostete Anruf-Aufnahme- und Analyse-Appliance auf einem **Youyeetoo R1 (RK3588S)** Einplatinenrechner.
+Nimmt Gespräche auf (PC/Teams über USB-Gadget **und** iPhone über Bluetooth-HFP), transkribiert mit Whisper
+(Encoder auf der NPU), trennt Sprecher akustisch (Diarization + Stimm-Profile) und erzeugt eine strukturierte
+KI-Zusammenfassung (Gemma-3-4B auf der NPU) — **komplett offline**, keine Cloud.
+
+## Inhaltsverzeichnis
+
+| Dokument | Inhalt |
+|---|---|
+| [01 – Hardware](docs/01-hardware.md) | Board, Audio-Hardware, USB-Gadget, Thermik, NPU |
+| [02 – Audio-Topologie](docs/02-audio-topologie.md) | PipeWire-Graph: callmix, Loopbacks, Noise-Gate, Volume-Bridges |
+| [03 – Aufnahme-Pipeline](docs/03-aufnahme-pipeline.md) | Aufnahme → Transkription → Diarization → LLM → Datenbank |
+| [04 – Sprechertrennung](docs/04-diarization.md) | Diarization, Anchor-Merge-Konsolidierung, Stimm-Profile |
+| [05 – LLM-Analyse](docs/05-llm-analyse.md) | Gemma-3-4B/NPU, Analyse-Pfade, strukturierte Zusammenfassung, Glossar |
+| [06 – iPhone-Bluetooth](docs/06-iphone-bt.md) | HFP-Pfad, Routing-Watcher, Echo-Fix |
+| [07 – Betrieb](docs/07-betrieb.md) | Services, Zugänge, Backups, Troubleshooting |
+| [08 – Changelog](docs/08-changelog.md) | Chronik aller Entwicklungsschritte |
+
+## System-Überblick
+
+```mermaid
+flowchart LR
+    subgraph Quellen
+        PC["Windows-PC<br/>(Teams, Medien)"]
+        IPHONE["iPhone<br/>(Telefonate)"]
+        USER(("Nutzer<br/>Logi H390 Headset"))
+    end
+
+    subgraph R1["Youyeetoo R1 (RK3588S, Armbian, lüfterlos)"]
+        PW["PipeWire<br/>Audio-Routing<br/>(callmix + micgate)"]
+        APP["CallRec Web-App<br/>Node.js :3000"]
+        WH["Whisper large-v3-turbo<br/>Encoder auf NPU"]
+        DIAR["Diarization<br/>sherpa-onnx + TitaNet"]
+        LLM["Gemma-3-4B<br/>rkllm auf NPU"]
+        DB[("MariaDB<br/>callrec")]
+    end
+
+    PC -- "USB-C (UAC2-Gadget)" --> PW
+    IPHONE -- "Bluetooth HFP (AX210)" --> PW
+    USER -- "USB-A" --> PW
+    PW -- "callrec_mix" --> APP
+    APP --> WH --> DIAR --> LLM --> DB
+    APP --- DB
+```
+
+## Quick Facts
+
+- **Board:** `192.168.1.200` (WLAN, primär) / `192.168.1.50` (LAN), Login `root`
+- **Web-GUI:** `http://192.168.1.200:3000` — Aufnahme, Transkript, Sprecher-Editor, Glossar
+- **App-Verzeichnis:** `/opt/callrec` (Node.js, systemd `callrec.service`)
+- **Harte Anforderungen:** immer offline (kein Cloud-LLM), akustische Sprecher-ID, kein aktiver Lüfter
+- Details und alle Zugangsdaten: [07 – Betrieb](docs/07-betrieb.md)
+
+## Doku-Regeln
+
+- Diese Doku ist die **verbindliche Ablage** für alle zukünftigen Änderungen am System.
+- Jede Änderung: betroffenes Kapitel aktualisieren **und** Eintrag in [08 – Changelog](docs/08-changelog.md).
+- Prozesse/Abläufe immer mit **Mermaid-Diagramm** dokumentieren (Gitea rendert sie direkt).
+- Auf dem Board bleiben `.bak-*`-Dateien als Rollback-Punkte; Meilenstein-Snapshots unter `/opt/callrec/milestones/`.