Matrix Bot Konsolidierung: 21 NestJS-Bots → 1 Go Binary

Einer der größten Architektur-Umbauten im ManaCore-Monorepo: 21 separate NestJS Matrix-Bot-Prozesse komplett ersetzt durch ein einziges Go-Binary mit Plugin-Architektur. Dazu Legacy-Code aufgeräumt, CI/CD migriert und Docker-Compose aktualisiert.

Das Problem: 21 NestJS-Prozesse

Jeder Matrix-Bot lief als eigenständiger NestJS-Service mit eigenem Docker-Container:

Ressourcenverbrauch vorher

Die Lösung: Go Binary mit Plugin-Architektur

Architektur-Entscheidungen

Warum Go?

• RAM: Go-Prozesse brauchen ~10-30 MB statt ~100 MB pro NestJS-Instanz
• Binary: Ein statisch kompiliertes Binary, kein node_modules
• Concurrency: 21 Matrix /sync-Loops als Goroutines (quasi kostenlos)
• Startup: <1 Sekunde für alle 21 Plugins
• Docker: Alpine-basiert, 7.5 MB statt ~200 MB pro Image
• Konsistenz: Passt zum bestehenden Go Sync-Server (mana-sync)

Projektstruktur

services/mana-matrix-bot/          # 50 Dateien, 7.620 Zeilen Go
├── cmd/server/main.go             # Entry Point (21 Plugin-Imports)
├── internal/
│   ├── config/config.go           # Env-Config mit Legacy-Token-Support
│   ├── runtime/
│   │   ├── runtime.go             # Plugin-Orchestrator, Sync-Loops, Event-Routing
│   │   └── health.go              # Health + Prometheus Metrics
│   ├── matrix/
│   │   ├── client.go              # mautrix-go Wrapper
│   │   ├── markdown.go            # Markdown→HTML (Port von TypeScript)
│   │   └── types.go               # IsBot, IsEdit, IsText Guards
│   ├── plugin/
│   │   ├── plugin.go              # Plugin Interface + SessionManager
│   │   ├── registry.go            # Compile-time Registration
│   │   ├── command.go             # !command Router
│   │   └── keyword.go             # Keyword-Detector (DE/EN)
│   ├── session/
│   │   ├── session.go             # In-Memory Store
│   │   └── redis.go               # Redis Store (Cross-Bot SSO)
│   ├── services/
│   │   ├── backend.go             # Generic HTTP Client
│   │   ├── voice.go               # STT/TTS Client
│   │   ├── auth.go                # Login via mana-core-auth
│   │   └── credit.go              # Credit Balance & Consumption
│   └── plugins/                   # 21 Plugin-Verzeichnisse
│       ├── gateway/               # Composite: AI + Todo + Cal + Clock + Voice
│       ├── todo/                  # Vollständig: !todo, !list, !done, !delete, etc.
│       ├── calendar/              # !heute, !morgen, !woche, !termine
│       ├── clock/                 # !timer, !stop, !alarm, !zeit
│       ├── contacts/              # !kontakte, !suche, !favoriten, !edit
│       ├── zitare/                # !zitat, !suche, !kategorie, !favoriten
│       ├── planta/                # !pflanzen, !giessen, !fällig, !historie
│       ├── ollama/                # AI Chat, !models, !all, !mode
│       ├── stt/                   # Audio→Text, !language, !model
│       ├── tts/                   # Text→Audio, !voice, !speed
│       └── ... (11 weitere)
├── Dockerfile                     # Multi-stage Alpine Build
├── go.mod / go.sum
└── CLAUDE.md

Vorher → Nachher: Die Zahlen

Ressourcen

Codebase

Docker Compose

Plugin Interface

Jedes Plugin implementiert ein minimales Interface:

type Plugin interface {
    Name() string
    Init(ctx context.Context, cfg PluginConfig) error
    HandleTextMessage(ctx context.Context, mc *MessageContext) error
    Commands() []CommandDef
}

// Optional: Audio und Image Handler
type AudioHandler interface {
    HandleAudioMessage(ctx context.Context, mc *MessageContext, audioData []byte) error
}

Neues Plugin hinzufügen = 3 Schritte:

1. internal/plugins/mybot/mybot.go erstellen
2. plugin.Register("mybot", ...) in init()
3. Import in main.go

Feature-Vollständigkeit der Plugins

Voll portiert (mit allen Commands)

Skeleton (Grundgerüst mit !help, !status)

stats, chat, manadeck, nutriphi, picture, presi, questions, skilltree, storage, projectdoc, onboarding

Runtime-Architektur

┌─────────────────────────────────────────────────┐
│                    main.go                       │
│   21 Plugin-Imports → init() Registration        │
├─────────────────────────────────────────────────┤
│                   Runtime                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐         │
│  │ Plugin 1│  │ Plugin 2│  │Plugin 21│  ...     │
│  │ @mana-  │  │ @todo-  │  │ @tts-   │         │
│  │  bot    │  │  bot    │  │  bot    │         │
│  └────┬────┘  └────┬────┘  └────┬────┘         │
│       │            │            │                │
│  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐         │
│  │mautrix  │  │mautrix  │  │mautrix  │         │
│  │Client 1 │  │Client 2 │  │Client 21│         │
│  └────┬────┘  └────┬────┘  └────┬────┘         │
├───────┼────────────┼────────────┼────────────────┤
│       └────────────┼────────────┘                │
│              Matrix /sync                        │
│         (21 Goroutines, ~0 RAM)                  │
├──────────────────────────────────────────────────┤
│  Health :4000   │  Sessions (Redis/Memory)       │
│  Metrics        │  Auth Client → mana-core-auth  │
│  Login/Logout   │  Credit Client                 │
└──────────────────────────────────────────────────┘

Event-Flow:

1. Matrix /sync empfängt Event
2. Runtime filtert: eigene Messages, Bot-Messages, Edits
3. Room-Allowlist-Check
4. !login/!logout global abgefangen
5. Text → Plugin.HandleTextMessage()
6. Audio → Plugin.HandleAudioMessage() (wenn implementiert)

Globale Features

Login/Logout (Runtime-Level)

User: !login [email protected] meinpasswort
Bot:  ✅ Angemeldet als [email protected]

User: !logout
Bot:  ✅ Abgemeldet.

Wird im Runtime abgefangen, bevor es an Plugins geht. Token in Redis gespeichert → alle Plugins haben sofort Zugriff.

Redis Sessions

Sessions persistent über Container-Restarts. Alle 21 Plugins teilen sich den Session-Store:

Redis Key: mana-bot:session:token:@user:mana.how
Value:     {token: "eyJ...", expires_at: "2026-03-28T..."}

Legacy Cleanup

Gelöscht

Was bleibt

• services/mana-matrix-bot/ — Der Go-Service
• Ein mana-matrix-bot Service in docker-compose
• Ein build-mana-matrix-bot CI Job
• Historische Devlog-Referenzen (als Dokumentation)

CI/CD

GitHub Actions

• CI: build-mana-matrix-bot Job mit Docker Multi-Platform Build (amd64 + arm64)
• CD: Auto-Deploy bei Changes in services/mana-matrix-bot/
• Change Detection: Nur Go-Service, keine Shared-Package-Dependencies mehr

Deployment

ssh mana-server
cd ~/projects/manacore-monorepo && git pull
./scripts/mac-mini/build-app.sh mana-matrix-bot
curl http://localhost:4000/health
# → {"status":"ok","plugins":["todo","calendar",...],"count":21}

Fazit

Die 2 GB RAM-Ersparnis auf dem Mac Mini sind besonders wertvoll — das ist Platz für 2-3 weitere Web-Apps oder ein größeres Ollama-Modell.