# 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/