Matrix-Chat: Architektur­konzept & Umsetzungs­empfehlung

0TL;DR — die Kernentscheidungen

1Technische Komponenten

Es braucht genau vier Bausteine — drei davon existieren schon oder sind Standardsoftware. Neu gebaut wird nur die Web-Component und das Orchestrator-Modul.

flowchart TB
    subgraph clients ["Clients"]
        SA["Standalone-Chat
(statische Shell-Seite
+ Web-Component)"]
        EMB["Bestehendes Produkt
(Web-Component
eingebettet)"]
    end

    subgraph products ["Produkt-Backends (mehrere)"]
        P1["Produkt A
(Vorgänge / Requests)"]
        P2["Produkt B
(Vorgänge / Requests)"]
    end

    ORCH["Chat-Orchestrator
(eigener kleiner Service, neu)"]
    P1 -- "REST + Service-Token:
Request angenommen" --> ORCH
    P2 -- "REST + Service-Token" --> ORCH

    KC["Keycloak
(vorhanden)
Realm pro Tenant"]
    SYN["Synapse Homeserver
(einer für alle Tenants,
keine Föderation)"]
    PG[("PostgreSQL")]
    PGO[("PostgreSQL
(Mapping + Standalone-Vorgänge)")]
    LK["LiveKit
(vorhanden, Video)"]

    SA -- "OIDC-Login" --> KC
    EMB -. "hat bereits
Keycloak-Session" .-> KC
    SA -- "Keycloak-Token" --> ORCH
    EMB -- "Keycloak-Token" --> ORCH
    ORCH -- "validiert Token
(JWKS)" --> KC
    ORCH -- "Admin-API: User anlegen,
Räume erstellen, einladen,
Matrix-Token ausstellen" --> SYN
    SA -- "Matrix Client-Server-API
(sync, senden, lesen)" --> SYN
    EMB -- "Matrix Client-Server-API" --> SYN
    SYN --- PG
    ORCH --- PGO
    ORCH -. "LiveKit-JWT
(später)" .-> LK
    

2Die zwei Modi: Standalone & Embedded

Kernidee: Es gibt keinen Unterschied im Chat-Stack zwischen den Modi. Der einzige Unterschied ist, woher das Keycloak-Token kommt und welche Räume angezeigt werden.

<chat-widget
  orchestrator-url="https://chat-api.example.com"
  request-id="4711">
</chat-widget>

widget.getKeycloakToken = () =>
  keycloak.token; // Host-App liefert

3Rollenmodell & Keycloak

Drei Realm-Rollen genügen. Der Tenant ist implizit durch das Realm (Subdomain) gegeben und wird als Claim mitgegeben — kein eigenes Tenant-Attribut pro User nötig.

Token-Claims

Der Orchestrator braucht aus dem Access-Token nur:

{
  "sub": "8f3a…",                        // stabile User-ID → Basis der Matrix-ID
  "preferred_username": "m.mustermann",
  "iss": "https://auth.example.com/realms/acme",  // → Tenant "acme"
  "realm_access": { "roles": ["chat-berater"] }
}

4Übersetzung: Keycloak-Rolle → Matrix-Rechte

Die Übersetzung passiert an genau zwei Stellen: beim Token-Exchange (User-Provisionierung) und beim Erstellen/Einladen in Räume (Power Level setzen). Danach arbeitet Matrix autark.

Rollenänderungen

Verliert ein User die Berater-Rolle, wird das beim nächsten Token-Exchange erkannt; der Orchestrator senkt dann seine Power Levels bzw. entfernt ihn aus Räumen (MVP: lazy beim Login; später: Keycloak-Event-Listener/Webhook für sofortige Wirkung).

5Raum-Template & Power-Level-Konzept

Jeder Raum hängt am Vorgang, nicht am Personen-Paar. Alias-Schema: #<tenant>.req-<requestId>:matrix.example.com. Der Orchestrator merkt sich nur das Mapping requestId ↔ roomId — mehr Schatten-Datenhaltung braucht es nicht.

createRoom-Template (vom Bot ausgeführt)

{
  "preset": "private_chat",
  "room_alias_name": "acme.req-4711",
  "name": "Baufinanzierung #4711",
  "creation_content": { "m.federate": false },
  "initial_state": [
    { "type": "m.room.join_rules",         "content": { "join_rule": "invite" } },
    { "type": "m.room.history_visibility", "content": { "history_visibility": "shared" } },
    { "type": "m.room.guest_access",       "content": { "guest_access": "forbidden" } },
    { "type": "com.example.request",       "content": { "tenant": "acme", "requestId": "4711" } }
  ],
  "power_level_content_override": {
    "users":          { "@chat-bot:matrix.example.com": 100,
                        "@acme.b.schmidt:matrix.example.com": 50 },
    "users_default":  0,
    "events_default": 0,        // PL 0 darf Nachrichten senden → Kunde kann schreiben
    "state_default":  100,      // Raum-Einstellungen nur der Bot
    "invite": 50, "kick": 50, "ban": 50, "redact": 50,
    "events": {
      "m.room.name": 100, "m.room.topic": 100,
      "m.room.avatar": 100, "m.room.power_levels": 100
    }
  },
  "invite": [ "@acme.b.schmidt:matrix.example.com",
              "@acme.k.mueller:matrix.example.com" ]
}

Das Custom-State-Event com.example.request verankert den fachlichen Kontext im Raum selbst — nützlich für das Widget (Titelzeile, Deep-Link zum Vorgang) und für Betrieb/Debugging.

Relevante Matrix-Mechanismen im Überblick

6Der Chat-Orchestrator

Der Orchestrator ist die einzige Stelle, an der Produkte, Keycloak und Matrix zusammenkommen. Er ist bewusst klein: fünf Endpunkte, ein Bot-User, zwei DB-Tabellen.

Anbindung der Produkte (Machine-to-Machine)

Jedes Produkt-Backend erhält einen Keycloak-Service-Account (Client-Credentials-Flow) und ruft den Orchestrator per REST auf — z. B. beim „Request angenommen“. Der Orchestrator prüft am Service-Token, welches Produkt und welcher Tenant aufruft. Kein Event-Bus, kein Message-Broker: ein synchroner, idempotenter REST-Call reicht für diese Frequenz völlig; das Produkt kann ihn bei Fehlern einfach wiederholen.

Aufgaben & API

Später POST /api/chat/rooms/{requestId}/call-token — LiveKit-JWT für Videocall, Raumname = Matrix-Room-ID, Berechtigung = Matrix-Mitgliedschaft. Mehr Kopplung braucht LiveKit nicht.

Was der Orchestrator bewusst nicht tut: Nachrichten proxien (der Chat-Traffic läuft direkt Client ↔ Synapse — der Orchestrator ist nie im heißen Pfad) und Fachlogik abbilden (Vorgänge gehören den Produkten).

7Die konkreten Flows

7.1 Login / Token-Exchange (beide Modi)

sequenceDiagram
    autonumber
    participant U as Browser (Widget)
    participant KC as Keycloak
    participant O as Orchestrator
    participant S as Synapse

    alt Standalone
        U->>KC: OIDC-Redirect-Login (Realm aus Subdomain)
        KC-->>U: Access-Token
    else Embedded
        Note over U: Produkt hat Keycloak-Session,
liefert Token per Callback
    end
    U->>O: POST /api/chat/token (Bearer: Keycloak-Token)
    O->>O: Token validieren (JWKS),
Tenant + Rollen extrahieren
    opt Erster Login
        O->>S: Admin-API: User @acme.k.mueller anlegen
    end
    O->>S: Admin-API: Access-Token für User ausstellen
    S-->>O: Matrix-Access-Token
    O-->>U: { mxid, accessToken, homeserverUrl }
    U->>S: /sync — Chat läuft ab jetzt direkt
    

7.2 Berater nimmt Vorgang an → Raum entsteht

sequenceDiagram
    autonumber
    participant B as Berater (Produkt-UI)
    participant P as Produkt-Backend
    participant O as Orchestrator (Service)
    participant S as Synapse

    B->>P: Request #4711 annehmen
    P->>P: Fachliche Zuweisung
    P->>O: POST /api/chat/rooms (Service-Token)
{ requestId, beraterId, kundeId }
    O->>S: Alias #acme.req-4711 auflösen
    alt Raum existiert noch nicht
        O->>S: Bot: createRoom (Template §5)
PLs: Bot 100, Berater 50, Kunde 0
        O->>O: Mapping requestId ↔ roomId speichern
    end
    O->>S: Bot: invite Berater + Kunde
    S-->>B: Raum erscheint im Sync des Beraters
    Note over S: Kunde sieht den Raum beim
nächsten Öffnen des Chats
    

7.3 Weiterer Berater wird hinzugefügt

sequenceDiagram
    autonumber
    participant B as Berater A (Widget)
    participant O as Orchestrator
    participant S as Synapse
    participant B2 as Berater B

    B->>O: GET /api/chat/colleagues (Einladen-Dialog)
    O-->>B: Berater-Liste des Tenants
    B->>O: POST /rooms/4711/participants { userId: B2 }
    O->>O: Prüfen: A ist chat-berater, gleicher Tenant,
Mitglied im Raum (oder berater-admin)
    O->>S: Bot: invite @acme.b2 + Power Level 50 setzen
    S-->>B2: Einladung im Sync → Auto-Join im Widget
    Note over B2: Sieht dank history_visibility=shared
den bisherigen Verlauf
    

Der Kunde hat diesen Dialog nie: das Widget blendet ihn bei PL < 50 aus, der Orchestrator lehnt den Call ohne Berater-Rolle ab, und Synapse würde einen direkten /invite mit PL 0 ohnehin mit 403 beantworten — dreifach dicht, entscheidend sind die beiden Server-Schichten.

7.4 Standalone ohne bestehendes Produkt

sequenceDiagram
    autonumber
    participant K as Kunde (Standalone-Chat)
    participant O as Orchestrator
    participant S as Synapse
    participant B as Berater (Standalone/Produkt)

    K->>O: „Neue Anfrage“ (Thema optional)
    O->>O: Leichtgewichtigen Vorgang anlegen
(Status: offen, kein Berater)
    O->>S: Bot: Raum erstellen, Kunde einladen
    Note over B: Eingangs-Ansicht zeigt offene Anfragen
(Orchestrator-Query, kein Matrix nötig)
    B->>O: Anfrage annehmen
    O->>S: Bot: Berater einladen, PL 50
    K-->>B: Chat läuft — identisch zu 7.2
    

So bleibt die Regel „Räume hängen an Vorgängen“ auch ohne Produkt erhalten — der Vorgang ist dann eben minimal (ID, Tenant, Status, Thema). Wächst später ein Produkt darum, ist nichts umzubauen.

8Durchsetzung: Warum Kunden auch per API nichts können

UI-Ausblenden ist Komfort, keine Sicherheit. Die Durchsetzung hat drei Schichten — die untersten zwei sind serverseitig und gelten für jeden API-Client, auch für einen Kunden mit curl und seinem eigenen Matrix-Token.

9Multi-Tenancy & Isolation

flowchart LR
    subgraph acme ["Tenant acme — acme.example.com"]
        KCA["Keycloak-Realm acme"]
        UA["@acme.k.mueller
@acme.b.schmidt"]
    end
    subgraph beta ["Tenant beta — beta.example.com"]
        KCB["Keycloak-Realm beta"]
        UB["@beta.k.weber
@beta.b.krause"]
    end
    subgraph syn ["Ein Synapse — matrix.example.com"]
        RA["#acme.req-4711
#acme.req-4712"]
        RB["#beta.req-0815"]
        MOD["Synapse-Modul:
Invites nur innerhalb
desselben Tenant-Präfixes"]
    end
    UA --> RA
    UB --> RB
    UA -. "✗ blockiert" .-x RB
    MOD --- RA
    MOD --- RB
    

Ein Homeserver oder einer pro Tenant?

Isolation konkret:

• Identität: MXID = @<tenant>.<user>:matrix.example.com; Tenant kommt aus dem Realm (iss-Claim), nie vom Client.
• Räume: Alias-Präfix pro Tenant; Tenant zusätzlich als State-Event im Raum.
• Zugriff: invite-only + Invites nur durch Bot/Berater + Modul-Check „gleicher Präfix“ → ein Cross-Tenant-Kontakt ist strukturell nicht herstellbar.
• Sichtbarkeit: keine öffentliche Raumliste, keine globale Nutzersuche, kein Presence.
• Orchestrator: prüft bei jedem Call, dass Aufrufer-Tenant == Ziel-Tenant.

Matrix Spaces? Optional, kein Bestandteil der Isolation. Sinnvoll erst, wenn Berater viele Räume haben und eine gruppierte Übersicht brauchen („alle offenen Fälle“). Das MVP löst das über die Vorgangs-Ansicht des Produkts bzw. die Eingangs-Ansicht des Orchestrators.

10Kubernetes-Fähigkeit (ohne es jetzt zu bauen)

Nichts am Konzept setzt Kubernetes voraus — und nichts verhindert es. Diese Regeln jetzt einhalten, dann ist der Umzug später ein Deployment-Thema, kein Architektur-Thema:

• Orchestrator zustandslos halten (Zustand nur in seiner DB) — als eigener, containerisierter Service ist er später ein gewöhnliches Deployment mit n Replicas.
• Konfiguration ausschließlich über Env-Vars/Secrets, keine Pfade oder Hosts hart verdrahten.
• PostgreSQL extern betreiben (managed oder eigener Server), nicht im Container-Lifecycle.
• Synapse-Media auf S3-kompatiblen Storage statt lokales Dateisystem — der einzige echte Stolperstein für Container-Betrieb.
• Synapse als Monolith starten; das Worker-Modell für horizontale Skalierung existiert und kann später aktiviert werden — erst relevant ab vielen tausend aktiven Nutzern.
• TLS am Edge (heute Caddy/Reverse-Proxy, später Ingress) — die Dienste selbst sprechen HTTP.
• Subdomain-Tenancy ist Host-Header-Routing — funktioniert mit jedem Ingress unverändert.
• Health-Endpoints (/health) von Anfang an vorsehen.

11MVP-Empfehlung & Roadmap

12Checkliste: alle Ausgangsfragen in einem Satz

Welche Komponenten brauchen wir?

Synapse, Keycloak (vorhanden), Orchestrator-Modul, Web-Component — LiveKit bleibt am Rand (§1).

Wie funktioniert Standalone?

Statische Shell mit OIDC-Login + dieselbe Web-Component; Anfragen ohne Produkt über den „Neue Anfrage“-Flow (§2, §7.4).

Wie funktioniert Embedded?

Produkt liefert das Keycloak-Token per Callback, Widget tauscht es beim Orchestrator gegen ein Matrix-Token und zeigt den Raum zum Vorgang (§2, §7.1).

Wer erstellt Räume?

Immer der Orchestrator-Bot, ausgelöst durch „Request angenommen“ (§7.2).

Raum an requestId oder an Berater+Kunde?

An die requestId — wegen Übergaben, Mehrfach-Beratern und Audit (§5).

Wie kommt ein weiterer Berater in den Raum?

Über den Orchestrator-Endpunkt mit Tenant- und Rollenprüfung; der Bot lädt ein und setzt PL 50 (§7.3).

Rolle des Orchestrators? Als Modul im bestehenden Backend?

Übersetzer Produkte/Keycloak → Matrix, nie im Nachrichtenpfad. Als eigener kleiner Service, weil mehrere Produkte den Chat nutzen — ein Andockpunkt statt Modul-Kopien; bewusst ohne Fachlogik gehalten (§6).

Keycloak-Rollen sinnvoll? Geeignet für Chat-Funktionen?

Drei Realm-Rollen; geeignet für die globale Frage „was für ein Nutzer ist das“, nicht für Raum-Laufzeitrechte — das machen Power Levels (§3, §4).

Wie übersetzt man Keycloak → Matrix?

Beim Token-Exchange und beim Raum-Erstellen/Einladen: Rolle → Power Level (0/50), Bot 100, invite-only, history shared (§4, §5).

Wie sind Kunden auch API-seitig beschränkt?

Power Levels + Join Rules serverseitig, plus Synapse-Modul gegen Raum-Erstellung/Fremd-Invites — die UI ist nur die dritte, kosmetische Schicht (§8).

Tenant-Isolation?

Präfix in MXIDs/Aliassen, Realm-basierte Tenant-Ermittlung, invite-only, Modul-Check, keine Suche/Presence (§9).

Gemeinsamer oder getrennter Homeserver?

Gemeinsam; getrennte Instanzen bleiben pro Tenant nachrüstbar (§9).

Spaces?

Optional, später, kein Isolationsmechanismus (§9).

Kubernetes?

Zustandsloser Orchestrator, Env-Config, externes Postgres, S3-Media — dann ist K8s reines Deployment (§10).

Wie bleibt es simpel?

Ein Homeserver, ein Modul, eine Komponente, kein Proxy, kein E2EE im MVP, alles Weitere additiv (§11).