mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 23:01:09 +02:00
2b979d5548
Completed migration of all Matrix bots to @manacore/bot-services: **SessionService (11 bots migrated):** - matrix-chat-bot (with conversation/model mapping via setSessionData) - matrix-contacts-bot - matrix-skilltree-bot - matrix-presi-bot - matrix-questions-bot - matrix-storage-bot - matrix-planta-bot - matrix-manadeck-bot - matrix-nutriphi-bot (with pendingImage via setSessionData) - matrix-picture-bot (previous commit) - matrix-zitare-bot (previous commit) **TranscriptionService (5 bots migrated):** - matrix-todo-bot (previous commit) - matrix-clock-bot (previous commit) - matrix-zitare-bot (previous commit) - matrix-nutriphi-bot - matrix-project-doc-bot **Code Reduction:** - Deleted 22 local module files (session + transcription) - ~1100 lines of duplicate code removed total - All bots now share identical auth and STT logic **Special handling:** - matrix-chat-bot: Extended methods converted to setSessionData/getSessionData - matrix-nutriphi-bot: pendingImage state via setSessionData - matrix-project-doc-bot: TranscriptionService used by MediaService Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
990 lines
36 KiB
Markdown
990 lines
36 KiB
Markdown
# ManaCore Matrix Bot Architecture
|
|
|
|
**Status:** Production
|
|
**Datum:** 1. Februar 2026
|
|
**Autor:** Till Schneider
|
|
**Letzte Aktualisierung:** 1. Februar 2026
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
ManaCore setzt auf **Matrix** als primäre Messaging-Plattform für Bot-Interaktionen. Mit 19 spezialisierten Matrix-Bots und einem Gateway-Bot bieten wir eine vollständig dezentrale, DSGVO-konforme Alternative zu Cloud-basierten Chat-Diensten.
|
|
|
|
**Kernprinzipien:**
|
|
- **Volle Kontrolle** - Eigene Infrastruktur, eigene Daten
|
|
- **DSGVO-Konformität** - Alle Daten auf eigenen Servern
|
|
- **Unabhängigkeit** - Keine Abhängigkeit von Drittanbieter-Plattformen
|
|
- **Einheitliche UX** - Konsistente Erfahrung über alle Bots
|
|
|
|
---
|
|
|
|
## 1. Warum Matrix?
|
|
|
|
### 1.1 Die Entscheidung gegen Telegram/Discord/Slack
|
|
|
|
Bei der Wahl der Messaging-Plattform für ManaCore hatten wir mehrere Optionen:
|
|
|
|
| Plattform | Vorteile | Nachteile |
|
|
|-----------|----------|-----------|
|
|
| **Telegram** | Große Reichweite, einfache API | Zentral, Daten bei Telegram, keine Kontrolle über UX |
|
|
| **Discord** | Gaming-Community, Webhooks | US-basiert, DSGVO-Bedenken, Werbung |
|
|
| **Slack** | Business-Standard | Teuer, Vendor Lock-in, keine Self-Hosting Option |
|
|
| **Matrix** | Dezentral, Self-Hosted, E2E-Verschlüsselung | Kleinere Community, mehr Setup-Aufwand |
|
|
|
|
**Unsere Entscheidung:** Matrix bietet die einzige Möglichkeit, eine **vollständig unabhängige** Plattform zu betreiben mit:
|
|
- Voller Kontrolle über Nutzerdaten
|
|
- Eigener UI/UX (Element, eigene Clients)
|
|
- End-to-End-Verschlüsselung
|
|
- Federation für Inter-Server-Kommunikation
|
|
|
|
### 1.2 Matrix Grundkonzepte
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Matrix Ökosystem │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Homeserver │<───>│ Homeserver │ Federation │
|
|
│ │ (mana.how) │ │ (matrix.org) │ │
|
|
│ └────────┬────────┘ └─────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐│
|
|
│ │ Räume ││
|
|
│ ├─────────────────────────────────────────────────────────────┤│
|
|
│ │ !abc:mana.how │ Bot-Interaktion (1:1) ││
|
|
│ │ !xyz:mana.how │ Gruppen-Chat (Multi-User) ││
|
|
│ │ #public:mana.how │ Öffentlicher Raum ││
|
|
│ └─────────────────────────────────────────────────────────────┘│
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐│
|
|
│ │ Clients ││
|
|
│ ├─────────────────────────────────────────────────────────────┤│
|
|
│ │ Element (Web/Desktop/Mobile) ││
|
|
│ │ FluffyChat, Nheko, SchildiChat, ... ││
|
|
│ │ ManaCore Bots (matrix-bot-sdk) ││
|
|
│ └─────────────────────────────────────────────────────────────┘│
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Kernkonzepte:**
|
|
- **Homeserver:** Der Server, der Nutzerkonten und Räume hostet (wir nutzen Synapse)
|
|
- **Räume:** Container für Nachrichten, Events und State
|
|
- **Federation:** Server können miteinander kommunizieren
|
|
- **E2E-Verschlüsselung:** Megolm/Olm für sichere Kommunikation
|
|
|
|
---
|
|
|
|
## 2. Bot-Architektur Übersicht
|
|
|
|
### 2.1 Gesamtarchitektur
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ ManaCore Bot Ecosystem │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
|
│ │ @manacore/bot-services (Shared Business Logic) │ │
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │
|
|
│ │ │ TodoSvc │ │ CalSvc │ │ AiSvc │ │ ClockSvc │ │ ... │ │ │
|
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Matrix Transport Layer │ │
|
|
│ │ (matrix-bot-sdk) │ │
|
|
│ └──────────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────────────┼──────────────────────────┐ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ 19 Matrix Bots │ │ Gateway Bot │ │ Shared Services │ │
|
|
│ │ (Specialized) │ │ (All-in-One) │ │ (mana-llm, etc) │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Backend APIs │ │
|
|
│ │ chat │ todo │ contacts │ calendar │ clock │ picture │ ... │ │
|
|
│ └──────────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Data Layer │ │
|
|
│ │ PostgreSQL │ S3/MinIO │ JSON Files │ Redis │ Ollama │ │
|
|
│ └──────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2.2 Bot-Typen
|
|
|
|
Wir unterscheiden drei Hauptkategorien von Bots:
|
|
|
|
#### Typ 1: Backend-integrierte Bots
|
|
Diese Bots fungieren als Interface zu bestehenden NestJS-Backend-APIs:
|
|
|
|
```
|
|
User → Matrix Bot → REST API → PostgreSQL
|
|
```
|
|
|
|
**Beispiele:**
|
|
- `matrix-contacts-bot` → Contacts Backend (Port 3015)
|
|
- `matrix-chat-bot` → Chat Backend (Port 3002)
|
|
- `matrix-picture-bot` → Picture Backend (Port 3006)
|
|
|
|
**Vorteile:**
|
|
- Konsistente Geschäftslogik (Web + Bot identisch)
|
|
- Zentralisierte Datenhaltung
|
|
- Einheitliche Auth via JWT
|
|
|
|
#### Typ 2: DSGVO-konforme Standalone-Bots
|
|
Diese Bots speichern Daten lokal ohne externe Services:
|
|
|
|
```
|
|
User → Matrix Bot → JSON File (lokal)
|
|
```
|
|
|
|
**Beispiele:**
|
|
- `matrix-todo-bot` → Lokale JSON-Datei
|
|
- `matrix-calendar-bot` → Lokale JSON-Datei
|
|
- `matrix-ollama-bot` → In-Memory + lokales Ollama
|
|
|
|
**Vorteile:**
|
|
- Keine Daten verlassen den Server
|
|
- Volle DSGVO-Konformität
|
|
- Offline-fähig
|
|
|
|
#### Typ 3: Gateway-Bot
|
|
Kombiniert alle Features in einem Bot:
|
|
|
|
```
|
|
User → matrix-mana-bot → @manacore/bot-services → Multiple Backends
|
|
```
|
|
|
|
**Features:**
|
|
- Einheitlicher Einstiegspunkt (`!mana`)
|
|
- Intelligentes Command-Routing
|
|
- Cross-Feature-Integration (z.B. "Termin mit Kontakt erstellen")
|
|
|
|
---
|
|
|
|
## 3. Shared Package: @manacore/bot-services
|
|
|
|
### 3.1 Architektur
|
|
|
|
Das Package `@manacore/bot-services` stellt transport-agnostische Geschäftslogik bereit:
|
|
|
|
```typescript
|
|
// Business Logic Services
|
|
export { TodoModule, TodoService } from './todo';
|
|
export { CalendarModule, CalendarService } from './calendar';
|
|
export { AiModule, AiService } from './ai';
|
|
export { ClockModule, ClockService } from './clock';
|
|
|
|
// Infrastructure Services (NEU: Konsolidiert aus 11+ Bots)
|
|
export { SessionModule, SessionService } from './session'; // Auth via mana-core-auth
|
|
export { TranscriptionModule, TranscriptionService } from './transcription'; // STT via mana-stt
|
|
|
|
// Storage Provider (pluggable)
|
|
export { FileStorageProvider } from './shared/storage/file-storage.provider';
|
|
export { MemoryStorageProvider } from './shared/storage/memory-storage.provider';
|
|
|
|
// Utilities
|
|
export { generateId, getTodayISO, formatDateDE } from './shared/utils';
|
|
export { parseGermanDateKeyword } from './shared/date-parser';
|
|
```
|
|
|
|
### 3.1.1 Konsolidierte Services
|
|
|
|
Die folgenden Services wurden aus den einzelnen Bots konsolidiert:
|
|
|
|
| Service | Vorher | Nachher | Migrierte Bots |
|
|
|---------|--------|---------|----------------|
|
|
| `SessionService` | 11x dupliziert | 1x in bot-services | picture, contacts, chat, zitare, skilltree, presi, questions, storage, planta, manadeck, nutriphi |
|
|
| `TranscriptionService` | 6x dupliziert | 1x in bot-services | todo, clock, zitare, nutriphi, project-doc |
|
|
|
|
**Status: Vollständig migriert** - Alle 11 Bots mit SessionService und alle 5 Bots mit TranscriptionService nutzen jetzt die gemeinsamen Services aus `@manacore/bot-services`.
|
|
|
|
### 3.2 TodoService
|
|
|
|
Vollständige Aufgabenverwaltung mit deutscher Sprachunterstützung:
|
|
|
|
```typescript
|
|
interface TodoService {
|
|
// CRUD
|
|
addTask(userId: string, text: string): Promise<Task>;
|
|
listTasks(userId: string, filter?: TaskFilter): Promise<Task[]>;
|
|
completeTask(userId: string, taskId: string): Promise<Task>;
|
|
deleteTask(userId: string, taskId: string): Promise<void>;
|
|
|
|
// Projekte
|
|
createProject(userId: string, name: string): Promise<Project>;
|
|
listProjects(userId: string): Promise<Project[]>;
|
|
|
|
// Filter
|
|
getTasksDueToday(userId: string): Promise<Task[]>;
|
|
getTasksByPriority(userId: string, priority: Priority): Promise<Task[]>;
|
|
}
|
|
|
|
// Deutsche Eingabeverarbeitung
|
|
"Morgen Arzt anrufen #gesundheit !hoch"
|
|
→ { text: "Arzt anrufen", dueDate: tomorrow, project: "gesundheit", priority: "high" }
|
|
```
|
|
|
|
### 3.3 CalendarService
|
|
|
|
Terminverwaltung mit natürlicher Spracheingabe:
|
|
|
|
```typescript
|
|
interface CalendarService {
|
|
// Events
|
|
createEvent(userId: string, input: string): Promise<Event>;
|
|
getEventsForDate(userId: string, date: Date): Promise<Event[]>;
|
|
getEventsInRange(userId: string, start: Date, end: Date): Promise<Event[]>;
|
|
|
|
// Kalender
|
|
createCalendar(userId: string, name: string): Promise<Calendar>;
|
|
listCalendars(userId: string): Promise<Calendar[]>;
|
|
}
|
|
|
|
// Natürliche Eingabe
|
|
"Meeting morgen um 14 Uhr im Büro"
|
|
→ { title: "Meeting", date: tomorrow, time: "14:00", location: "Büro" }
|
|
```
|
|
|
|
### 3.4 AiService
|
|
|
|
Integration mit lokalem LLM (Ollama) und mana-llm:
|
|
|
|
```typescript
|
|
interface AiService {
|
|
chat(userId: string, message: string): Promise<string>;
|
|
setModel(userId: string, model: string): Promise<void>;
|
|
setSystemPrompt(userId: string, mode: SystemMode): Promise<void>;
|
|
clearHistory(userId: string): Promise<void>;
|
|
|
|
// Vision (für Bildanalyse)
|
|
analyzeImage(userId: string, imageUrl: string, prompt: string): Promise<string>;
|
|
}
|
|
|
|
type SystemMode = 'default' | 'classify' | 'summarize' | 'translate' | 'code';
|
|
```
|
|
|
|
### 3.5 Storage Provider Pattern
|
|
|
|
Pluggable Storage für flexible Datenhaltung:
|
|
|
|
```typescript
|
|
interface StorageProvider<T> {
|
|
get(key: string): Promise<T | null>;
|
|
set(key: string, value: T): Promise<void>;
|
|
delete(key: string): Promise<void>;
|
|
list(prefix?: string): Promise<string[]>;
|
|
}
|
|
|
|
// Implementierungen
|
|
class FileStorageProvider<T> implements StorageProvider<T> {
|
|
constructor(private basePath: string) {}
|
|
// Speichert als JSON-Dateien
|
|
}
|
|
|
|
class MemoryStorageProvider<T> implements StorageProvider<T> {
|
|
private store = new Map<string, T>();
|
|
// In-Memory für Tests
|
|
}
|
|
|
|
// Zukünftig möglich:
|
|
class PostgresStorageProvider<T> implements StorageProvider<T> { }
|
|
class RedisStorageProvider<T> implements StorageProvider<T> { }
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Matrix Bot Implementation
|
|
|
|
### 4.1 Technologie-Stack
|
|
|
|
Alle Matrix-Bots nutzen einen einheitlichen Stack:
|
|
|
|
| Komponente | Technologie | Version |
|
|
|------------|-------------|---------|
|
|
| **Framework** | NestJS | 10.x |
|
|
| **Matrix SDK** | matrix-bot-sdk | 0.7.1 |
|
|
| **Language** | TypeScript | 5.x |
|
|
| **Runtime** | Node.js | 20.x |
|
|
| **Build** | tsc + Docker | - |
|
|
|
|
### 4.2 Bot-Struktur
|
|
|
|
```
|
|
services/matrix-{name}-bot/
|
|
├── src/
|
|
│ ├── app.module.ts # NestJS Root Module
|
|
│ ├── main.ts # Bootstrap
|
|
│ ├── matrix/
|
|
│ │ ├── matrix.module.ts # Matrix SDK Integration
|
|
│ │ ├── matrix.service.ts # Bot-Logik & Command-Handling
|
|
│ │ └── matrix.constants.ts # Konfiguration
|
|
│ ├── services/ # Optionale lokale Services
|
|
│ └── utils/ # Hilfsfunktionen
|
|
├── Dockerfile
|
|
├── package.json
|
|
└── tsconfig.json
|
|
```
|
|
|
|
### 4.3 Matrix Service Pattern
|
|
|
|
```typescript
|
|
@Injectable()
|
|
export class MatrixService implements OnModuleInit, OnModuleDestroy {
|
|
private client: MatrixClient;
|
|
private storage: SimpleFsStorageProvider;
|
|
|
|
async onModuleInit() {
|
|
// Storage für Sync-State
|
|
this.storage = new SimpleFsStorageProvider('./data/matrix-state.json');
|
|
|
|
// Client initialisieren
|
|
this.client = new MatrixClient(
|
|
this.configService.get('MATRIX_HOMESERVER_URL'),
|
|
this.configService.get('MATRIX_ACCESS_TOKEN'),
|
|
this.storage,
|
|
);
|
|
|
|
// Crypto für E2E (optional)
|
|
const cryptoStore = new RustSdkCryptoStorageProvider('./data/crypto');
|
|
await this.client.crypto.prepare(cryptoStore);
|
|
|
|
// Event-Handler registrieren
|
|
this.client.on('room.message', this.handleMessage.bind(this));
|
|
|
|
// Sync starten
|
|
await this.client.start();
|
|
}
|
|
|
|
private async handleMessage(roomId: string, event: any) {
|
|
if (event.sender === this.client.getUserId()) return;
|
|
|
|
const body = event.content?.body;
|
|
if (!body?.startsWith('!')) return;
|
|
|
|
const [command, ...args] = body.slice(1).split(' ');
|
|
|
|
switch (command.toLowerCase()) {
|
|
case 'help':
|
|
case 'hilfe':
|
|
await this.sendHelp(roomId);
|
|
break;
|
|
case 'add':
|
|
case 'hinzufuegen':
|
|
await this.handleAdd(roomId, event.sender, args.join(' '));
|
|
break;
|
|
// ... weitere Commands
|
|
}
|
|
}
|
|
|
|
private async sendMessage(roomId: string, message: string) {
|
|
await this.client.sendMessage(roomId, {
|
|
msgtype: 'm.text',
|
|
body: message,
|
|
format: 'org.matrix.custom.html',
|
|
formatted_body: this.markdownToHtml(message),
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.4 Command-Pattern
|
|
|
|
Alle Bots nutzen ein einheitliches Command-Schema:
|
|
|
|
```
|
|
!command [args] # Englisch
|
|
!befehl [argumente] # Deutsch (Aliase)
|
|
```
|
|
|
|
**Beispiele:**
|
|
|
|
| Bot | Command | Alias | Beschreibung |
|
|
|-----|---------|-------|--------------|
|
|
| todo | `!add Task` | `!hinzufuegen` | Aufgabe erstellen |
|
|
| todo | `!list` | `!liste` | Aufgaben anzeigen |
|
|
| todo | `!done 1` | `!erledigt` | Aufgabe abschließen |
|
|
| calendar | `!today` | `!heute` | Termine heute |
|
|
| calendar | `!add Meeting morgen 14:00` | `!termin` | Termin erstellen |
|
|
| contacts | `!search Max` | `!suche` | Kontakt suchen |
|
|
|
|
### 4.5 Nummer-basiertes Referenzsystem
|
|
|
|
Für intuitive Interaktion nutzen Bots ein Listen-Referenz-System:
|
|
|
|
```
|
|
User: !kontakte
|
|
Bot: 1. Max Mustermann (max@example.com)
|
|
2. Anna Schmidt (anna@example.com)
|
|
3. Peter Meyer (peter@example.com)
|
|
|
|
User: !anrufen 2
|
|
Bot: Anruf an Anna Schmidt wird vorbereitet...
|
|
Telefon: +49 123 456789
|
|
```
|
|
|
|
**Implementierung:**
|
|
```typescript
|
|
// Pro User wird die letzte Liste gespeichert
|
|
private listCache = new Map<string, Contact[]>();
|
|
|
|
async handleList(roomId: string, userId: string) {
|
|
const contacts = await this.contactsApi.list(userId);
|
|
this.listCache.set(userId, contacts);
|
|
|
|
const message = contacts
|
|
.map((c, i) => `${i + 1}. ${c.name} (${c.email})`)
|
|
.join('\n');
|
|
|
|
await this.sendMessage(roomId, message);
|
|
}
|
|
|
|
async handleCall(roomId: string, userId: string, index: number) {
|
|
const contacts = this.listCache.get(userId);
|
|
if (!contacts || index < 1 || index > contacts.length) {
|
|
return this.sendMessage(roomId, 'Ungültige Nummer');
|
|
}
|
|
|
|
const contact = contacts[index - 1];
|
|
// ... Anruf-Logik
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Bot-Katalog
|
|
|
|
### 5.1 Produktivitäts-Bots
|
|
|
|
| Bot | Port | Storage | Beschreibung |
|
|
|-----|------|---------|--------------|
|
|
| **matrix-mana-bot** | 3310 | JSON | Gateway - alle Features vereint |
|
|
| **matrix-todo-bot** | 3314 | JSON | Aufgabenverwaltung mit Projekten |
|
|
| **matrix-calendar-bot** | 3315 | JSON | Terminverwaltung mit Erinnerungen |
|
|
| **matrix-clock-bot** | 3318 | API | Timer, Alarme, Weltuhren |
|
|
|
|
### 5.2 KI & Medien-Bots
|
|
|
|
| Bot | Port | Backend | Beschreibung |
|
|
|-----|------|---------|--------------|
|
|
| **matrix-chat-bot** | 3327 | chat:3002 | KI-Konversationen |
|
|
| **matrix-ollama-bot** | 3311 | mana-llm:3025 | Lokales LLM (DSGVO) |
|
|
| **matrix-picture-bot** | 3319 | picture:3006 | AI-Bildgenerierung |
|
|
| **matrix-tts-bot** | 3023 | mana-tts:3022 | Text-to-Speech |
|
|
| **matrix-project-doc-bot** | 3313 | PostgreSQL+S3 | Projektdoku → Blog |
|
|
|
|
### 5.3 App-Integrations-Bots
|
|
|
|
| Bot | Port | Backend | Beschreibung |
|
|
|-----|------|---------|--------------|
|
|
| **matrix-contacts-bot** | 3320 | contacts:3015 | Kontaktverwaltung |
|
|
| **matrix-storage-bot** | 3323 | storage:3016 | Cloud-Speicher |
|
|
| **matrix-nutriphi-bot** | 3316 | nutriphi:3023 | Ernährungstracking |
|
|
| **matrix-zitare-bot** | 3321 | zitare:3019 | Tägliche Zitate |
|
|
| **matrix-questions-bot** | 3324 | questions:3011 | Q&A mit Web-Recherche |
|
|
| **matrix-manadeck-bot** | 3321 | manadeck:3009 | Kartendecks & Lernen |
|
|
| **matrix-planta-bot** | 3322 | planta:3022 | Pflanzenpflege |
|
|
| **matrix-skilltree-bot** | 3324 | skilltree:3024 | Skill Tree & XP |
|
|
| **matrix-presi-bot** | 3308 | presi:3008 | Präsentationen |
|
|
| **matrix-stats-bot** | 3312 | Umami | Analytics-Reports |
|
|
|
|
---
|
|
|
|
## 6. Authentifizierung
|
|
|
|
### 6.1 Zwei Auth-Modelle
|
|
|
|
Wir unterstützen zwei Authentifizierungsmodelle:
|
|
|
|
#### Modell A: Matrix User ID (DSGVO-optimiert)
|
|
Für Standalone-Bots ohne Backend-Anbindung:
|
|
|
|
```
|
|
Matrix User ID → Isolierte Daten pro User
|
|
@till:mana.how → /data/till-mana-how/todos.json
|
|
```
|
|
|
|
**Vorteile:**
|
|
- Kein Login erforderlich
|
|
- Daten strikt isoliert
|
|
- Funktioniert offline
|
|
|
|
**Verwendung:** matrix-todo-bot, matrix-calendar-bot, matrix-ollama-bot
|
|
|
|
#### Modell B: Mana Core Auth (JWT)
|
|
Für Backend-integrierte Bots:
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Matrix User │────>│ Matrix Bot │────>│ mana-core-auth │
|
|
│ !login x y │ │ │ │ (Port 3001) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │
|
|
│ JWT Token │
|
|
▼ │
|
|
┌─────────────────┐ │
|
|
│ In-Memory Map │ │
|
|
│ @user → token │ │
|
|
└─────────────────┘ │
|
|
│ │
|
|
▼ │
|
|
┌─────────────────┐ │
|
|
│ Backend API │◀──────────┘
|
|
│ (JWT Validate) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
**Login-Flow:**
|
|
```
|
|
User: !login till@mana.how geheimespasswort
|
|
Bot: Login erfolgreich! Token gültig für 7 Tage.
|
|
Nutze !logout zum Abmelden.
|
|
|
|
User: !kontakte
|
|
Bot: [Zeigt Kontakte aus Backend]
|
|
```
|
|
|
|
**Verwendung:** matrix-contacts-bot, matrix-chat-bot, matrix-picture-bot, etc.
|
|
|
|
### 6.2 Token-Management
|
|
|
|
```typescript
|
|
@Injectable()
|
|
export class AuthService {
|
|
private tokens = new Map<string, TokenData>();
|
|
|
|
async login(matrixUserId: string, email: string, password: string): Promise<boolean> {
|
|
const response = await fetch(`${this.authUrl}/api/v1/auth/login`, {
|
|
method: 'POST',
|
|
headers: { 'Content-Type': 'application/json' },
|
|
body: JSON.stringify({ email, password }),
|
|
});
|
|
|
|
if (!response.ok) return false;
|
|
|
|
const { accessToken, expiresIn } = await response.json();
|
|
this.tokens.set(matrixUserId, {
|
|
token: accessToken,
|
|
expiresAt: Date.now() + expiresIn * 1000,
|
|
});
|
|
|
|
return true;
|
|
}
|
|
|
|
getToken(matrixUserId: string): string | null {
|
|
const data = this.tokens.get(matrixUserId);
|
|
if (!data || Date.now() > data.expiresAt) return null;
|
|
return data.token;
|
|
}
|
|
|
|
logout(matrixUserId: string): void {
|
|
this.tokens.delete(matrixUserId);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Datenbank-Anbindung
|
|
|
|
### 7.1 Vier Speichermodelle
|
|
|
|
| Modell | Technologie | Bots | Use Case |
|
|
|--------|-------------|------|----------|
|
|
| **Stateless** | Keine eigene | contacts, chat, picture | Backend delegiert |
|
|
| **JSON Files** | Lokale Dateien | todo, calendar, mana-bot | DSGVO, einfach |
|
|
| **PostgreSQL** | Drizzle ORM | project-doc-bot | Komplexe Relationen |
|
|
| **S3/MinIO** | AWS SDK | project-doc-bot | Medien-Speicherung |
|
|
|
|
### 7.2 JSON File Storage (DSGVO)
|
|
|
|
```typescript
|
|
// Struktur
|
|
/data/
|
|
├── {sanitized-matrix-user-id}/
|
|
│ ├── todos.json
|
|
│ ├── calendar.json
|
|
│ └── settings.json
|
|
```
|
|
|
|
```typescript
|
|
// FileStorageProvider
|
|
class FileStorageProvider<T> {
|
|
constructor(private basePath: string) {}
|
|
|
|
private getPath(key: string): string {
|
|
return path.join(this.basePath, `${key}.json`);
|
|
}
|
|
|
|
async get(key: string): Promise<T | null> {
|
|
const filePath = this.getPath(key);
|
|
if (!fs.existsSync(filePath)) return null;
|
|
const data = await fs.promises.readFile(filePath, 'utf-8');
|
|
return JSON.parse(data);
|
|
}
|
|
|
|
async set(key: string, value: T): Promise<void> {
|
|
const filePath = this.getPath(key);
|
|
await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
|
|
await fs.promises.writeFile(filePath, JSON.stringify(value, null, 2));
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7.3 PostgreSQL + Drizzle (Komplexe Bots)
|
|
|
|
```typescript
|
|
// schema.ts (project-doc-bot)
|
|
export const projects = pgTable('projects', {
|
|
id: uuid('id').primaryKey().defaultRandom(),
|
|
userId: varchar('user_id', { length: 255 }).notNull(),
|
|
name: varchar('name', { length: 255 }).notNull(),
|
|
description: text('description'),
|
|
createdAt: timestamp('created_at').defaultNow(),
|
|
});
|
|
|
|
export const mediaItems = pgTable('media_items', {
|
|
id: uuid('id').primaryKey().defaultRandom(),
|
|
projectId: uuid('project_id').references(() => projects.id),
|
|
type: varchar('type', { length: 50 }).notNull(), // photo, voice, text
|
|
s3Key: varchar('s3_key', { length: 500 }),
|
|
transcription: text('transcription'),
|
|
createdAt: timestamp('created_at').defaultNow(),
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Matrix-spezifische Features
|
|
|
|
### 8.1 Rich Media Support
|
|
|
|
Matrix-Bots können verschiedene Nachrichtentypen senden:
|
|
|
|
```typescript
|
|
// Text mit Markdown/HTML
|
|
await client.sendMessage(roomId, {
|
|
msgtype: 'm.text',
|
|
body: 'Plain text fallback',
|
|
format: 'org.matrix.custom.html',
|
|
formatted_body: '<b>Bold</b> and <code>code</code>',
|
|
});
|
|
|
|
// Bilder
|
|
await client.sendMessage(roomId, {
|
|
msgtype: 'm.image',
|
|
body: 'Generated image',
|
|
url: await client.uploadContent(imageBuffer, 'image/png'),
|
|
info: { w: 512, h: 512, mimetype: 'image/png' },
|
|
});
|
|
|
|
// Dateien
|
|
await client.sendMessage(roomId, {
|
|
msgtype: 'm.file',
|
|
body: 'report.pdf',
|
|
url: await client.uploadContent(pdfBuffer, 'application/pdf'),
|
|
info: { mimetype: 'application/pdf', size: pdfBuffer.length },
|
|
});
|
|
|
|
// Audio (für TTS)
|
|
await client.sendMessage(roomId, {
|
|
msgtype: 'm.audio',
|
|
body: 'Voice message',
|
|
url: await client.uploadContent(audioBuffer, 'audio/mp3'),
|
|
info: { mimetype: 'audio/mp3', duration: 5000 },
|
|
});
|
|
```
|
|
|
|
### 8.2 Reactions
|
|
|
|
Bots können auf Nachrichten reagieren:
|
|
|
|
```typescript
|
|
// Bestätigung
|
|
await client.sendEvent(roomId, 'm.reaction', {
|
|
'm.relates_to': {
|
|
rel_type: 'm.annotation',
|
|
event_id: originalEventId,
|
|
key: '✅',
|
|
},
|
|
});
|
|
|
|
// Fehler
|
|
await client.sendEvent(roomId, 'm.reaction', {
|
|
'm.relates_to': {
|
|
rel_type: 'm.annotation',
|
|
event_id: originalEventId,
|
|
key: '❌',
|
|
},
|
|
});
|
|
```
|
|
|
|
### 8.3 Reply Threading
|
|
|
|
```typescript
|
|
await client.sendMessage(roomId, {
|
|
msgtype: 'm.text',
|
|
body: '> Original message\n\nMy reply',
|
|
format: 'org.matrix.custom.html',
|
|
formatted_body: '<mx-reply>...</mx-reply>My reply',
|
|
'm.relates_to': {
|
|
'm.in_reply_to': {
|
|
event_id: originalEventId,
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
### 8.4 End-to-End Encryption
|
|
|
|
```typescript
|
|
// Crypto Storage initialisieren
|
|
const cryptoStore = new RustSdkCryptoStorageProvider('./data/crypto');
|
|
|
|
// Client mit E2E
|
|
const client = new MatrixClient(homeserverUrl, accessToken, storage);
|
|
await client.crypto.prepare(cryptoStore);
|
|
|
|
// Verschlüsselten Raum beitreten
|
|
await client.joinRoom(encryptedRoomId);
|
|
|
|
// Nachrichten werden automatisch ver-/entschlüsselt
|
|
await client.sendMessage(encryptedRoomId, {
|
|
msgtype: 'm.text',
|
|
body: 'This will be encrypted',
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Deployment
|
|
|
|
### 9.1 Docker Configuration
|
|
|
|
```dockerfile
|
|
# Dockerfile
|
|
FROM node:20-alpine AS builder
|
|
|
|
WORKDIR /app
|
|
|
|
# Workspace files
|
|
COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
|
|
|
|
# Shared packages
|
|
COPY packages/bot-services ./packages/bot-services
|
|
|
|
# Bot
|
|
COPY services/matrix-todo-bot ./services/matrix-todo-bot
|
|
|
|
RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
|
|
RUN pnpm install --frozen-lockfile
|
|
RUN pnpm --filter @manacore/bot-services build
|
|
RUN pnpm --filter matrix-todo-bot build
|
|
|
|
# Production
|
|
FROM node:20-alpine AS production
|
|
|
|
WORKDIR /app/services/matrix-todo-bot
|
|
|
|
COPY --from=builder /app/node_modules/.pnpm /app/node_modules/.pnpm
|
|
COPY --from=builder /app/services/matrix-todo-bot/node_modules ./node_modules
|
|
COPY --from=builder /app/services/matrix-todo-bot/dist ./dist
|
|
COPY --from=builder /app/services/matrix-todo-bot/package.json ./
|
|
|
|
# Data volume für persistente Speicherung
|
|
VOLUME /app/data
|
|
|
|
ENV NODE_ENV=production
|
|
EXPOSE 3314
|
|
|
|
CMD ["node", "dist/main.js"]
|
|
```
|
|
|
|
### 9.2 Environment Variables
|
|
|
|
```env
|
|
# Matrix Connection
|
|
MATRIX_HOMESERVER_URL=https://matrix.mana.how
|
|
MATRIX_ACCESS_TOKEN=syt_xxx...
|
|
MATRIX_USER_ID=@todo-bot:mana.how
|
|
|
|
# Auth (für Backend-Integration)
|
|
MANA_CORE_AUTH_URL=http://mana-core-auth:3001
|
|
|
|
# Storage
|
|
DATA_PATH=/app/data
|
|
|
|
# Optional: Backend URLs
|
|
TODO_BACKEND_URL=http://todo-backend:3018
|
|
CONTACTS_BACKEND_URL=http://contacts-backend:3015
|
|
|
|
# Optional: AI Services
|
|
MANA_LLM_URL=http://mana-llm:3025
|
|
```
|
|
|
|
### 9.3 docker-compose.yml
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
|
|
services:
|
|
matrix-todo-bot:
|
|
build:
|
|
context: .
|
|
dockerfile: services/matrix-todo-bot/Dockerfile
|
|
environment:
|
|
- MATRIX_HOMESERVER_URL=${MATRIX_HOMESERVER_URL}
|
|
- MATRIX_ACCESS_TOKEN=${MATRIX_TODO_BOT_TOKEN}
|
|
- MATRIX_USER_ID=@todo-bot:mana.how
|
|
volumes:
|
|
- todo-bot-data:/app/data
|
|
networks:
|
|
- manacore
|
|
restart: unless-stopped
|
|
healthcheck:
|
|
test: ["CMD", "wget", "-q", "--spider", "http://localhost:3314/health"]
|
|
interval: 30s
|
|
timeout: 10s
|
|
retries: 3
|
|
|
|
matrix-calendar-bot:
|
|
# ... analog
|
|
|
|
matrix-mana-bot:
|
|
# Gateway mit allen Services
|
|
depends_on:
|
|
- mana-llm
|
|
- todo-backend
|
|
- contacts-backend
|
|
|
|
volumes:
|
|
todo-bot-data:
|
|
calendar-bot-data:
|
|
mana-bot-data:
|
|
|
|
networks:
|
|
manacore:
|
|
external: true
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Port-Allokation
|
|
|
|
### Matrix Bots (3308-3327)
|
|
|
|
| Port | Service | Beschreibung |
|
|
|------|---------|--------------|
|
|
| 3308 | matrix-presi-bot | Präsentationen |
|
|
| 3310 | matrix-mana-bot | Gateway (All-in-One) |
|
|
| 3311 | matrix-ollama-bot | Lokales LLM |
|
|
| 3312 | matrix-stats-bot | Analytics |
|
|
| 3313 | matrix-project-doc-bot | Projektdoku |
|
|
| 3314 | matrix-todo-bot | Aufgaben |
|
|
| 3315 | matrix-calendar-bot | Termine |
|
|
| 3316 | matrix-nutriphi-bot | Ernährung |
|
|
| 3318 | matrix-clock-bot | Timer/Alarme |
|
|
| 3319 | matrix-picture-bot | Bildgenerierung |
|
|
| 3320 | matrix-contacts-bot | Kontakte |
|
|
| 3321 | matrix-zitare-bot | Zitate |
|
|
| 3322 | matrix-planta-bot | Pflanzen |
|
|
| 3323 | matrix-storage-bot | Cloud-Speicher |
|
|
| 3324 | matrix-questions-bot | Q&A |
|
|
| 3327 | matrix-chat-bot | KI-Chat |
|
|
|
|
### Supporting Services
|
|
|
|
| Port | Service | Beschreibung |
|
|
|------|---------|--------------|
|
|
| 3001 | mana-core-auth | Authentifizierung |
|
|
| 3020 | mana-stt | Speech-to-Text |
|
|
| 3021 | mana-search | Web-Recherche |
|
|
| 3022 | mana-tts | Text-to-Speech |
|
|
| 3025 | mana-llm | LLM-Abstraction |
|
|
|
|
---
|
|
|
|
## 11. Vorteile gegenüber Drittanbieter-Plattformen
|
|
|
|
### 11.1 Vollständige Kontrolle
|
|
|
|
| Aspekt | Telegram/Discord | ManaCore Matrix |
|
|
|--------|------------------|-----------------|
|
|
| **Datenhoheit** | Bei Anbieter | Bei uns |
|
|
| **Verfügbarkeit** | Abhängig von Anbieter | Eigene Infrastruktur |
|
|
| **API-Änderungen** | Anbieter entscheidet | Wir entscheiden |
|
|
| **Preisänderungen** | Anbieter entscheidet | Keine |
|
|
| **Zensur/Sperrung** | Möglich | Nicht möglich |
|
|
|
|
### 11.2 DSGVO-Konformität
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────┐
|
|
│ DSGVO-Compliance │
|
|
├────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ✅ Datenverarbeitung nur auf eigenen Servern │
|
|
│ ✅ Keine Weitergabe an Dritte │
|
|
│ ✅ Löschung auf Anfrage (Art. 17) │
|
|
│ ✅ Auskunft über gespeicherte Daten (Art. 15) │
|
|
│ ✅ Datenportabilität (Art. 20) │
|
|
│ ✅ Auftragsverarbeitungsvertrag nicht nötig │
|
|
│ │
|
|
└────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 11.3 Einheitliche UX
|
|
|
|
Da wir beide Seiten kontrollieren (Bot + Client), können wir:
|
|
- Konsistente Command-Syntax über alle Bots
|
|
- Deutsche Sprachunterstützung überall
|
|
- Einheitliches Fehler-Handling
|
|
- Nahtlose Cross-Bot-Integration
|
|
|
|
---
|
|
|
|
## 12. Zukünftige Entwicklung
|
|
|
|
### 12.1 Geplante Erweiterungen
|
|
|
|
- **Widget-Integration:** Interaktive UIs direkt in Element
|
|
- **Voice-Bot:** Sprachsteuerung via Matrix Calls
|
|
- **Bot-Discovery:** Automatische Bot-Erkennung in Räumen
|
|
- **Mehr @manacore/bot-services:** Nutrition, Stats, Docs Services
|
|
|
|
### 12.2 Konsolidierung
|
|
|
|
Der Fokus liegt auf der Konsolidierung der Bot-Services in `@manacore/bot-services`:
|
|
- Alle wiederkehrende Logik zentral
|
|
- Einheitliche Storage-Abstraction
|
|
- Transport-agnostische Services
|
|
|
|
---
|
|
|
|
## 13. Fazit
|
|
|
|
ManaCore's Matrix-Bot-Architektur bietet eine **vollständig unabhängige, DSGVO-konforme** Alternative zu Cloud-basierten Chat-Diensten. Mit 19 spezialisierten Bots und einem Gateway-Bot decken wir alle Produktivitäts- und App-Integrationsszenarien ab.
|
|
|
|
**Kernvorteile:**
|
|
1. **Volle Kontrolle** über Daten und Infrastruktur
|
|
2. **DSGVO-Konformität** durch lokale Datenhaltung
|
|
3. **Einheitliche UX** durch konsistente Command-Patterns
|
|
4. **Skalierbarkeit** durch Microservices-Architektur
|
|
5. **Erweiterbarkeit** durch @manacore/bot-services
|
|
|
|
---
|
|
|
|
*Dokument erstellt am 1. Februar 2026*
|
|
*Letzte Aktualisierung: 1. Februar 2026*
|