KI-AGENT: Matrix-Kommunikationslösung entwerfen

docs/README.md

@@ -5,3 +5,4 @@ Diese Dokumentation unterstützt dich bei der täglichen Nutzung von FEDEO.
 ## Einstieg
 
 - [Bedienung](./bedienung/README.md)
+- [Kommunikationslösung auf Basis des Matrix-Standards](./kommunikationslösung-matrix.md)

docs/kommunikationslösung-matrix.md

@@ -0,0 +1,371 @@
+# Kommunikationslösung auf Basis des Matrix-Standards
+
+Dieser Entwurf beschreibt eine FEDEO-Kommunikationslösung für Chat, Anrufe und Videokonferenzen auf Basis des Matrix-Standards. Ziel ist eine souverän betreibbare Lösung, die Mandantenfähigkeit, Datenschutz, Rechteverwaltung und die bestehenden FEDEO-Workflows berücksichtigt.
+
+## Zielbild
+
+FEDEO erhält einen integrierten Kommunikationsbereich, der interne Zusammenarbeit und externe Kommunikation abdeckt:
+
+- Chat in Einzel-, Gruppen-, Projekt-, Vorgangs- und Kundenräumen
+- Audioanrufe aus Direktchats, Gruppenräumen und Kontakten
+- Videokonferenzen mit Bildschirmfreigabe und Einladungslinks
+- Ende-zu-Ende-verschlüsselte private Kommunikation
+- revisionsfähige Verknüpfung von relevanten Kommunikationsereignissen mit FEDEO-Objekten
+- optional föderierte Kommunikation mit externen Matrix-Organisationen
+
+Matrix wird dabei nicht als isolierter Messenger betrieben, sondern als Kommunikationsschicht neben dem bestehenden FEDEO-Backend.
+
+## Empfohlene Architektur
+
+```text
+Nutzerinnen und Nutzer
+  |
+  | FEDEO Web, Mobile App, optional Element Desktop/Mobile
+  v
+FEDEO Frontend
+  |
+  | FEDEO API, SSO, Rechte, Objektkontext
+  v
+FEDEO Backend
+  |
+  | Provisionierung, Webhooks, Audit-Metadaten
+  v
+Matrix Homeserver
+  |
+  +-- PostgreSQL für Matrix-Daten
+  +-- Redis für Worker und Caches
+  +-- Medien-Repository für Anhänge
+  +-- TURN/STUN für direkte Medienverbindungen
+  +-- MatrixRTC / LiveKit SFU für Gruppenanrufe und Videokonferenzen
+```
+
+### Kernkomponenten
+
+| Komponente | Empfehlung | Aufgabe |
+| --- | --- | --- |
+| Matrix Homeserver | Synapse | Standardnaher, bewährter Homeserver mit guter Betriebsdokumentation |
+| Matrix Client im FEDEO Web | Matrix JS SDK oder eingebetteter Element-Web-Ausschnitt | Chat, Raumliste, Nachrichten, Reaktionen, Anhänge |
+| Mobile Integration | Matrix SDK über FEDEO Mobile oder Deep Link zu Element X | Pushfähige mobile Kommunikation |
+| Identität | OIDC/SSO über FEDEO Auth, perspektivisch Matrix Authentication Service | Einheitlicher Login und zentrale Nutzerverwaltung |
+| Audio/Video | MatrixRTC mit Element Call und LiveKit SFU | Moderne Anrufe und Videokonferenzen |
+| NAT Traversal | coturn | STUN/TURN für stabile Medienverbindungen |
+| Reverse Proxy | bestehender Traefik-Ansatz | TLS, Routing, `.well-known/matrix/*` |
+| Administration | FEDEO Admin-Oberfläche plus Synapse Admin API | Nutzer, Räume, Richtlinien, Sperren |
+
+## Betriebsmodell
+
+Für FEDEO ist ein eigener Matrix-Homeserver pro Installation oder pro großer Betreiberinstanz sinnvoll. Der Matrix-Server sollte nicht öffentlich als offener Registrierungsserver betrieben werden. Nutzer werden ausschließlich durch FEDEO angelegt, aktualisiert und deaktiviert.
+
+Empfohlene Domains:
+
+- `app.example.com`: FEDEO Oberfläche
+- `matrix.example.com`: Matrix Client-Server und Federation API
+- `call.example.com`: Element Call / MatrixRTC
+- `livekit.example.com`: LiveKit SFU
+- `turn.example.com`: TURN/STUN
+
+Die öffentliche Matrix-Serverkennung kann trotzdem `example.com` lauten. Dafür werden `.well-known/matrix/client` und `.well-known/matrix/server` über Traefik ausgeliefert.
+
+## Mandantenmodell
+
+Matrix selbst ist raumbasiert, FEDEO ist mandantenbasiert. Deshalb sollte FEDEO die Mandantenlogik explizit auf Matrix-Räume und Spaces abbilden.
+
+### Räume und Spaces
+
+- Pro FEDEO-Mandant wird ein Matrix Space angelegt.
+- Projekte, Vorgänge, Helpdesk-Konversationen, interne Teams und Kundenkontakte werden als Räume im Mandanten-Space geführt.
+- Direkträume werden nutzerbezogen angelegt, aber über FEDEO mandantengebunden sichtbar gemacht.
+- Externe Räume erhalten einen klaren Status, zum Beispiel `intern`, `extern`, `kunde`, `lieferant`.
+
+### Raumalias-Konvention
+
+Beispiele:
+
+- `#tenant-<mandant>-team:example.com`
+- `#tenant-<mandant>-project-<projekt>:example.com`
+- `#tenant-<mandant>-ticket-<ticket>:example.com`
+- `#tenant-<mandant>-customer-<kunde>:example.com`
+
+Interne technische IDs sollten nicht als sichtbarer Anzeigename genutzt werden. Nutzerinnen und Nutzer sehen sprechende Namen wie `Projekt: Website Relaunch` oder `Kunde: Muster GmbH`.
+
+## Rechte und Rollen
+
+FEDEO bleibt führend für Berechtigungen. Matrix übernimmt die technische Durchsetzung im Raum.
+
+| FEDEO-Rolle | Matrix-Abbildung |
+| --- | --- |
+| Mandantenadmin | Space-Admin und Raumadmin |
+| Teamleitung | Moderatorin oder Moderator in Team- und Projekträumen |
+| Mitarbeitende | Mitglied mit Schreibrechten |
+| Externe Kontakte | Eingeschränkte Mitgliedschaft in ausgewählten Räumen |
+| Automationen | Application-Service- oder Bot-Nutzer mit minimalen Rechten |
+
+Änderungen an Rollen, Teams oder Mandantenzugehörigkeiten lösen im FEDEO-Backend eine Synchronisation mit Matrix aus. Beim Entzug eines Zugriffs wird die Person aus den betroffenen Räumen entfernt. Bei Ende-zu-Ende-verschlüsselten Räumen muss zusätzlich berücksichtigt werden, dass bereits erhaltene Nachrichten auf Geräten verbleiben können.
+
+## Chat
+
+Der Chat wird als erste Ausbaustufe umgesetzt.
+
+### Funktionen
+
+- Direktnachrichten
+- Gruppenräume
+- Mandanten-, Team-, Projekt- und Vorgangsräume
+- Datei- und Bildanhänge
+- Erwähnungen, Reaktionen und Lesestatus
+- Suche in nicht verschlüsselten Räumen über den Homeserver
+- lokale Suche in verschlüsselten Räumen über Client-Indizes
+- Verknüpfung von Nachrichten mit FEDEO-Objekten
+
+### Integration in FEDEO
+
+FEDEO sollte keine vollständige Kopie aller Nachrichten in der eigenen Datenbank speichern. Stattdessen speichert FEDEO nur Referenzen:
+
+- Matrix Raum-ID
+- Matrix Event-ID
+- FEDEO Objekt-Typ und Objekt-ID
+- Zeitstempel
+- beteiligter FEDEO-Nutzer
+- optionale Vorschau, falls Datenschutzrichtlinie dies erlaubt
+
+So bleibt Matrix das Kommunikationssystem, während FEDEO nachvollziehen kann, welche Kommunikation zu welchem Objekt gehört.
+
+## Audioanrufe
+
+Einzelanrufe können direkt über Matrix-VoIP in Direktchats gestartet werden. Der FEDEO-Client zeigt dafür in Kontakt-, Kunden-, Mitarbeitenden- und Chatansichten einen Anruf-Button.
+
+### Anforderungen
+
+- WebRTC-Unterstützung im Browser
+- STUN/TURN über coturn
+- Geräteauswahl für Mikrofon und Lautsprecher
+- Anrufbenachrichtigung im Web und mobil
+- Statusanzeige `verfügbar`, `beschäftigt`, `im Anruf`, `abwesend`
+
+Für klassische Telefonie kann später ein SIP-Gateway ergänzt werden. Das sollte jedoch getrennt von der ersten Matrix-Einführung betrachtet werden, damit Chat und WebRTC-Kommunikation nicht durch Telefoniekomplexität ausgebremst werden.
+
+## Videokonferenzen
+
+Für Gruppenanrufe und Videokonferenzen wird MatrixRTC mit Element Call und LiveKit empfohlen. Matrix übernimmt dabei Raumzustand, Identität, Berechtigungen und Signalisierung; LiveKit übernimmt als SFU die effiziente Medienverteilung.
+
+### Funktionen
+
+- Videokonferenzen aus Matrix-Räumen
+- spontane Besprechungen aus Projekten, Vorgängen oder Kundenakten
+- Bildschirmfreigabe
+- Einladungslink für externe Gäste
+- Wartebereich für externe Gäste
+- Moderationsrechte für Stummschalten, Entfernen und Raumverwaltung
+- optionale Aufzeichnung erst in einer späteren, gesondert freizugebenden Ausbaustufe
+
+### Konfiguration
+
+Clients finden den MatrixRTC-Dienst über `.well-known/matrix/client`. Dort wird der LiveKit-JWT-Dienst als `org.matrix.msc4143.rtc_foci` angekündigt. Diese Datei muss öffentlich lesbar sein, als JSON ausgeliefert werden und CORS für Webclients erlauben.
+
+Beispiel:
+
+```json
+{
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  },
+  "org.matrix.msc4143.rtc_foci": [
+    {
+      "type": "livekit",
+      "livekit_service_url": "https://call.example.com/livekit/jwt"
+    }
+  ]
+}
+```
+
+## Authentifizierung und Nutzerverwaltung
+
+FEDEO sollte Identität und Lebenszyklus der Nutzer zentral steuern.
+
+### Empfohlener Ablauf
+
+1. Nutzer wird in FEDEO angelegt.
+2. FEDEO erzeugt oder aktualisiert den Matrix-Nutzer.
+3. FEDEO weist den Nutzer den passenden Spaces und Räumen zu.
+4. Login erfolgt über FEDEO SSO/OIDC.
+5. Deaktivierung in FEDEO deaktiviert auch den Matrix-Zugang und entfernt Raumzugriffe.
+
+Die Matrix User-ID sollte stabil und nicht personenbezogen änderungsanfällig sein:
+
+```text
+@u_<fedeo_user_id>:example.com
+```
+
+Der Anzeigename kann weiterhin den echten Namen enthalten und bei Änderungen synchronisiert werden.
+
+## Datenschutz und Compliance
+
+Matrix erlaubt starke Datenschutzkonzepte, erfordert aber klare Betriebsregeln.
+
+### Empfehlungen
+
+- Ende-zu-Ende-Verschlüsselung für Direktnachrichten und vertrauliche Projekträume aktivieren.
+- Nicht verschlüsselte Räume nur dort nutzen, wo serverseitige Suche, Archivierung oder Compliance-Funktionen ausdrücklich benötigt werden.
+- Medienaufbewahrung mandantenweit konfigurierbar machen.
+- Externe Gäste optisch klar kennzeichnen.
+- Federation standardmäßig deaktivieren oder auf erlaubte Domains beschränken.
+- Aufzeichnungen von Videokonferenzen nur mit expliziter Einwilligung und sichtbarem Status erlauben.
+- Administrative Zugriffe protokollieren.
+- Klare Löschfristen für Räume, Anhänge und Audit-Referenzen definieren.
+
+## Federation
+
+Matrix kann mit anderen Homeservern föderieren. Für FEDEO sollte Federation als kontrollierbare Option umgesetzt werden.
+
+### Betriebsmodi
+
+| Modus | Beschreibung | Empfehlung |
+| --- | --- | --- |
+| geschlossen | Keine Federation, nur interne Nutzer und explizite Gäste | Standard für kleine Installationen |
+| allowlist | Federation nur mit freigegebenen Domains | Empfehlung für B2B-Kommunikation |
+| offen | Federation mit beliebigen Matrix-Servern | Nur für bewusst öffentliche Communities |
+
+Für steuer-, kunden- und projektnahe Kommunikation ist `allowlist` der beste Zielmodus.
+
+## Brücken zu anderen Systemen
+
+Matrix unterstützt Brücken zu anderen Kommunikationsdiensten. Für FEDEO sind Brücken nützlich, sollten aber nicht zur ersten Produktstufe gehören.
+
+Mögliche spätere Erweiterungen:
+
+- E-Mail-Brücke für Helpdesk- oder Kundenkommunikation
+- Slack- oder Teams-Brücke für externe Projektpartner
+- WhatsApp- oder SMS-Brücke nur nach gesonderter Datenschutzprüfung
+- SIP-Brücke für Telefonie
+
+Brücken müssen pro Mandant aktivierbar sein und brauchen klare Hinweise, welche Daten an externe Dienste fließen.
+
+## FEDEO-Produktoberfläche
+
+Die Kommunikation sollte in FEDEO an zwei Stellen sichtbar sein.
+
+### Globaler Kommunikationsbereich
+
+- Raumliste
+- Direktnachrichten
+- Suche
+- Anrufe
+- laufende Besprechungen
+- Benachrichtigungen
+
+### Objektbezogene Kommunikation
+
+In Projekten, Kunden, Vorgängen, Helpdesk-Tickets und Dokumenten erscheint ein Kommunikations-Tab:
+
+- zugeordneter Raum
+- relevante Nachrichtenreferenzen
+- Start von Chat, Anruf oder Besprechung
+- Teilnehmerverwaltung entsprechend FEDEO-Rechten
+
+So bleibt Kommunikation dort, wo die Arbeit stattfindet.
+
+## Backend-Integration
+
+Das FEDEO-Backend erhält ein Kommunikationsmodul mit folgenden Aufgaben:
+
+- Matrix-Nutzer provisionieren
+- Spaces und Räume anlegen
+- Raum-Mitgliedschaften synchronisieren
+- Matrix-Event-Webhooks empfangen
+- FEDEO-Objekte mit Matrix-Räumen verknüpfen
+- Benachrichtigungseinstellungen verwalten
+- Admin-Aktionen auditieren
+
+Technisch kann dies über Matrix Admin API, Client-Server API und Application Services erfolgen. Für Automationen empfiehlt sich ein eigener Application Service, weil er reservierte Nutzer- und Raum-Namensräume sauber verwalten kann.
+
+## Deployment-Erweiterung
+
+Der bestehende Docker-/Traefik-Ansatz kann um folgende Dienste erweitert werden:
+
+- `matrix-synapse`
+- `matrix-db` oder gemeinsame PostgreSQL-Instanz mit getrennter Datenbank
+- `redis`
+- `coturn`
+- `element-web` optional als Fallback-Client
+- `element-call`
+- `livekit`
+- `matrix-rtc-jwt-service`
+
+Für produktive Installationen sollte Matrix eine eigene PostgreSQL-Datenbank erhalten. Medien sollten in S3-kompatiblen Speicher ausgelagert werden, damit große Anhänge und Konferenzartefakte nicht den Applikationsserver füllen.
+
+## Monitoring
+
+Wichtige Kennzahlen:
+
+- aktive Nutzerinnen und Nutzer
+- Anzahl Räume pro Mandant
+- Nachrichtenrate
+- Medien-Speicherverbrauch
+- Zustellverzögerung
+- fehlgeschlagene Anrufe
+- LiveKit Paketverlust, Latenz und Teilnehmerzahl
+- TURN-Nutzung
+- Federation-Fehler
+
+Logs von FEDEO, Synapse, LiveKit, coturn und Traefik sollten über eine gemeinsame Korrelation, zum Beispiel Request-ID oder Nutzer-ID, untersuchbar sein.
+
+## Risiken und Gegenmaßnahmen
+
+| Risiko | Gegenmaßnahme |
+| --- | --- |
+| Komplexität durch zwei Systeme | FEDEO bleibt führend für Nutzer, Rechte und Objektbezug |
+| Datenschutz bei externen Räumen | Externe Kennzeichnung, Federation-Allowlist, Mandantenrichtlinien |
+| E2EE erschwert Suche und Archivierung | Raumtyp bewusst wählen, lokale Suche, Metadatenreferenzen statt Vollkopie |
+| Medienverbindungen scheitern in Firmennetzen | coturn sauber betreiben, UDP und TCP/TLS-Fallback anbieten |
+| Betriebskosten durch Video | LiveKit skalierbar betreiben, Limits pro Mandant definieren |
+| Gästezugriff wird unübersichtlich | Einladungslinks mit Ablaufdatum, Wartebereich, Moderationsrechte |
+
+## Umsetzung in Phasen
+
+### Phase 1: Fundament und Chat
+
+- Synapse mit PostgreSQL, Redis, Traefik und `.well-known` betreiben
+- FEDEO-Nutzer zu Matrix synchronisieren
+- Mandanten-Spaces und erste Teamräume anlegen
+- Chat im FEDEO-Frontend integrieren
+- Benachrichtigungen und Raumreferenzen speichern
+
+### Phase 2: Objektbezogene Kommunikation
+
+- Räume automatisch für Projekte, Vorgänge und Kunden anlegen
+- Kommunikations-Tab in FEDEO-Objekten ergänzen
+- Rechteänderungen aus FEDEO nach Matrix synchronisieren
+- externe Gäste einladen und kennzeichnen
+
+### Phase 3: Audio und Video
+
+- coturn bereitstellen
+- MatrixRTC, Element Call und LiveKit integrieren
+- Anruf- und Videobuttons in Chat, Kontakten und Projekten ergänzen
+- Gäste-Links und Wartebereich umsetzen
+
+### Phase 4: Compliance und Skalierung
+
+- Aufbewahrungsrichtlinien pro Mandant
+- Monitoring und Admin-Dashboards
+- Federation-Allowlist
+- optionale Brücken
+- optionale Aufzeichnung mit Einwilligungsworkflow
+
+## Offene Entscheidungen
+
+- Soll Federation initial deaktiviert oder direkt mit Allowlist ausgeliefert werden?
+- Welche Räume müssen serverseitig durchsuchbar sein und bleiben deshalb unverschlüsselt?
+- Sollen externe Gäste Matrix-Konten erhalten oder nur temporäre Konferenzzugänge?
+- Wird Element als sichtbarer Fallback-Client angeboten oder soll alles primär in FEDEO stattfinden?
+- Welche Mandantenlimits gelten für Speicher, Teilnehmerzahl und Videodauer?
+
+## Quellen und Standards
+
+- Matrix Specification: https://spec.matrix.org/
+- Matrix Application Services: https://matrix.org/docs/older/application-services/
+- Matrix Bridges: https://www.matrix.org/docs/communities/bridging/
+- Synapse Worker-Dokumentation: https://matrix-org.github.io/synapse/develop/workers.html
+- Element Call Self-Hosting: https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md
+- Element MatrixRTC Konfiguration: https://docs.element.io/latest/element-server-suite-pro/configuring-components/configuring-matrix-rtc/
+- LiveKit Self-Hosting: https://docs.livekit.io/transport/self-hosting/