# Matrix SDK — Pyramid Entwicklungsreferenz

> **Basis:** [`package:matrix`](https://pub.dev/packages/matrix) (Dart/Flutter Matrix SDK)  
> **Ziel:** Vollständige Landkarte aller Matrix-Funktionen mit Code-Snippets für den Pyramid-App-Bau.  
> **Referenz-Implementierung:** FluffyChat (https://gitlab.com/famedly/fluffychat)

---

## Navigation

| # | Thema | Beschreibung |
|---|-------|--------------|
| [01](01-auth.md) | **Authentifizierung** | Login, Logout, Register, SSO, Token-Management |
| [02](02-rooms.md) | **Räume & Spaces** | Erstellen, Beitreten, Verlassen, Spaces, Suche |
| [03](03-messages.md) | **Nachrichten & Events** | Senden, Timeline, Reaktionen, Edits, Threads, Polls |
| [04](04-dm.md) | **Direct Messages** | DM-Räume finden, starten, verwalten |
| [05](05-media.md) | **Medien & Dateien** | Upload, Download, Thumbnails, verschlüsselte Medien |
| [06](06-encryption.md) | **E2EE Verschlüsselung** | Keys, Verifizierung, Cross-Signing, Key-Backup |
| [07](07-push.md) | **Push & Notifications** | Pusher, Push Rules, FCM, lokale Benachrichtigungen |
| [08](08-voip.md) | **VoIP & Calls** | MatrixRTC, Legacy m.call, Klingel-Flow |
| [08b](08b-livekit-streaming.md) | **LiveKit Streaming** ⭐ | **Vollständige Server-Anleitung + Flutter-Implementierung** |
| [09](09-profile.md) | **Profil & Präsenz** | Avatar, Displayname, Presence, Account-Daten |
| [10](10-room-admin.md) | **Raum-Administration** | Power Levels, Moderierung, Einstellungen, Bans |
| [11](11-search.md) | **Suche & Discovery** | Nachrichten-Suche, User-Suche, Raum-Verzeichnis |
| [12](12-quick-reference.md) | **Schnellreferenz** | Alle Enums, Widget-Patterns, Fehlerhandling |
| [13](13-server-admin-continuwuity.md) | **Server-Admin Continuwuity** ⭐ | Admin API, Power Levels erzwingen, MSC3083, Diagnose |
| [CHECKLIST](CHECKLIST.md) | **Feature-Checklist** ⭐ | Implementierungsstand + Roadmap |

---

## Schnellreferenz: Client-Initialisierung

```dart
import 'package:matrix/matrix.dart';

final client = Client(
  'MeinApp',                              // App-Name (User-Agent)
  database: MatrixSdkDatabase(...),       // Persistenz (sqflite)
  nativeImplementations: NativeImplementationsIsolate(compute), // E2EE
  logLevel: Level.warning,
);

// Initialisieren (lädt gespeicherten Session-State)
await client.init(
  waitForFirstSync: false,               // UI nicht blockieren
  waitUntilLoadCompletedLoaded: false,
);
```

---

## Architektur-Überblick

```
Client
├── rooms: List<Room>               // alle bekannten Räume
├── userID: String?                 // eigene MXID (@user:server)
├── accessToken: String?            // Bearer-Token
├── homeserver: Uri                 // https://matrix.example.org
│
├── Room
│   ├── id: String                  // !roomId:server
│   ├── getTimeline()               // Event-Stream
│   ├── sendTextEvent()
│   ├── sendEvent()
│   ├── members                     // Map<String, User>
│   └── states                      // Map<String, Map<String, StrippedStateEvent>>
│
├── Event
│   ├── type: String                // m.room.message, m.reaction, …
│   ├── content: Map<String, dynamic>
│   ├── body: String                // text body (decrypted)
│   └── messageType: String?        // m.text, m.image, m.file, …
│
└── User
    ├── id: String                  // MXID
    ├── displayName: String?
    └── avatarUrl: Uri?
```

---

## Wichtige Streams / Provider-Hooks

```dart
// Auf Sync-Events reagieren
client.onSync.stream.listen((SyncUpdate update) { ... });

// Neue/geänderte Räume
client.onRoomUpdate.stream.listen((String roomId) { ... });

// Verbindungsstatus
client.onConnectionStateChanged.stream.listen((ConnectionState s) { ... });

// Eigener User geändert
client.onUserEvent.stream.listen((EventUpdate update) { ... });

// Benachrichtigungs-Events (gefiltert nach Push-Rules)
client.onNotification.stream.listen((Event event) { ... });
```

---

## Tipps für Riverpod-Integration

```dart
// Matrix-Client als Provider
final matrixClientProvider = FutureProvider<Client>((ref) async {
  final client = Client('Pyramid', ...);
  await client.init(waitForFirstSync: false);
  return client;
});

// Raumliste reaktiv
final roomsProvider = StreamProvider<List<Room>>((ref) async* {
  final client = await ref.watch(matrixClientProvider.future);
  yield client.rooms;
  await for (final _ in client.onSync.stream) {
    yield client.rooms;
  }
});
```