mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-21 01:26:43 +02:00
a532790d99
Features: - Random quotes and daily quote of the day - 10 categories (motivation, wisdom, love, life, success, etc.) - Search functionality - Login integration with Zitare backend - Favorites and lists management - Voice note transcription via mana-stt - Natural language command support (German/English)
178 lines
4.7 KiB
Markdown
178 lines
4.7 KiB
Markdown
# Matrix Zitare Bot - Claude Code Guidelines
|
|
|
|
## Overview
|
|
|
|
Matrix Zitare Bot provides daily inspirational quotes via Matrix chat. It includes a built-in collection of German quotes and integrates with the Zitare backend for user favorites and lists management.
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: NestJS 10
|
|
- **Matrix**: matrix-bot-sdk
|
|
- **Storage**: Built-in quotes + Zitare Backend API
|
|
- **Auth**: Mana Core Auth (JWT)
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Development
|
|
pnpm install
|
|
pnpm start:dev # Start with hot reload
|
|
|
|
# Build
|
|
pnpm build # Production build
|
|
|
|
# Type check
|
|
pnpm type-check # Check TypeScript types
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
services/matrix-zitare-bot/
|
|
├── src/
|
|
│ ├── main.ts # Application entry point (port 3317)
|
|
│ ├── app.module.ts # Root module
|
|
│ ├── health.controller.ts # Health check endpoint
|
|
│ ├── config/
|
|
│ │ └── configuration.ts # Configuration, help text, quotes data
|
|
│ ├── bot/
|
|
│ │ ├── bot.module.ts
|
|
│ │ └── matrix.service.ts # Matrix client & command handlers
|
|
│ ├── quotes/
|
|
│ │ ├── quotes.module.ts
|
|
│ │ ├── quotes.service.ts # Local quotes management
|
|
│ │ └── zitare.service.ts # Zitare Backend API client
|
|
│ └── session/
|
|
│ ├── session.module.ts
|
|
│ └── session.service.ts # User session & auth management
|
|
├── Dockerfile
|
|
└── package.json
|
|
```
|
|
|
|
## Bot Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `!help` | Show help message |
|
|
| `!zitat` | Random quote |
|
|
| `!heute` | Quote of the day |
|
|
| `!suche [text]` | Search quotes |
|
|
| `!kategorie [name]` | Quotes by category |
|
|
| `!kategorien` | Show all categories |
|
|
| `!login email pass` | Login to Zitare |
|
|
| `!logout` | Logout |
|
|
| `!favorit` | Save last quote to favorites |
|
|
| `!favoriten` | Show favorites |
|
|
| `!listen` | Show lists |
|
|
| `!liste [name]` | Create new list |
|
|
| `!addliste [nr]` | Add last quote to list |
|
|
| `!status` | Bot status |
|
|
|
|
## Natural Language Keywords
|
|
|
|
The bot responds to natural language (German + English):
|
|
- "zitat", "inspiration" -> Random quote
|
|
- "heute", "tageszitat" -> Daily quote
|
|
- "motiviere mich" -> Motivation quote
|
|
- "guten morgen" -> Motivation quote
|
|
- "kategorien" -> Show categories
|
|
- "hilfe", "help" -> Help message
|
|
|
|
## Voice Notes
|
|
|
|
Voice notes are transcribed via mana-stt service and parsed as commands:
|
|
- Say category names (e.g., "Motivation", "Liebe") for themed quotes
|
|
- Say search terms to find matching quotes
|
|
- Use natural language commands
|
|
|
|
## Quote Categories
|
|
|
|
- `motivation` - Motivationszitate
|
|
- `weisheit` - Weisheiten
|
|
- `liebe` - Liebeszitate
|
|
- `leben` - Lebenszitate
|
|
- `erfolg` - Erfolgszitate
|
|
- `glueck` - Gluckszitate
|
|
- `freundschaft` - Freundschaft
|
|
- `mut` - Mutzitate
|
|
- `hoffnung` - Hoffnungszitate
|
|
- `natur` - Naturzitate
|
|
|
|
## Environment Variables
|
|
|
|
```env
|
|
# Server
|
|
PORT=3317
|
|
|
|
# Matrix
|
|
MATRIX_HOMESERVER_URL=http://localhost:8008
|
|
MATRIX_ACCESS_TOKEN=syt_xxx
|
|
MATRIX_ALLOWED_ROOMS=#zitare:matrix.mana.how
|
|
MATRIX_STORAGE_PATH=./data/bot-storage.json
|
|
|
|
# Zitare Backend (for favorites/lists)
|
|
ZITARE_BACKEND_URL=http://localhost:3007
|
|
ZITARE_API_PREFIX=/api/v1
|
|
|
|
# Mana Core Auth
|
|
MANA_CORE_AUTH_URL=http://localhost:3001
|
|
|
|
# Speech-to-Text
|
|
STT_URL=http://localhost:3020
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
# Build locally
|
|
docker build -f services/matrix-zitare-bot/Dockerfile -t matrix-zitare-bot services/matrix-zitare-bot
|
|
|
|
# Run
|
|
docker run -p 3317:3317 \
|
|
-e MATRIX_HOMESERVER_URL=http://synapse:8008 \
|
|
-e MATRIX_ACCESS_TOKEN=syt_xxx \
|
|
-e ZITARE_BACKEND_URL=http://zitare-backend:3007 \
|
|
-e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
|
|
-v matrix-zitare-bot-data:/app/data \
|
|
matrix-zitare-bot
|
|
```
|
|
|
|
## Health Check
|
|
|
|
```bash
|
|
curl http://localhost:3317/health
|
|
```
|
|
|
|
## Getting a Matrix Access Token
|
|
|
|
```bash
|
|
# Login to get access token
|
|
curl -X POST "https://matrix.mana.how/_matrix/client/v3/login" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"type": "m.login.password",
|
|
"user": "zitare-bot",
|
|
"password": "your-password"
|
|
}'
|
|
|
|
# Response contains: {"access_token": "syt_xxx", ...}
|
|
```
|
|
|
|
## Zitare Backend API Endpoints Used
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/health` | GET | Health check |
|
|
| `/api/v1/favorites` | GET | Get user favorites |
|
|
| `/api/v1/favorites` | POST | Add favorite |
|
|
| `/api/v1/favorites/:id` | DELETE | Remove favorite |
|
|
| `/api/v1/lists` | GET | Get user lists |
|
|
| `/api/v1/lists` | POST | Create list |
|
|
| `/api/v1/lists/:id/quotes` | POST | Add quote to list |
|
|
|
|
## GDPR Compliance
|
|
|
|
- Built-in quotes stored locally (no external API)
|
|
- User favorites/lists stored in Zitare Backend database
|
|
- All data under user control
|
|
- No third-party tracking
|