managarten/services/matrix-manadeck-bot/CLAUDE.md

Matrix ManaDeck Bot - Claude Code Guidelines

Overview

Matrix ManaDeck Bot provides card/deck management via Matrix chat. It integrates with the ManaDeck backend for full CRUD operations, AI deck generation, study sessions, and spaced repetition progress tracking.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: ManaDeck API (port 3009)
• Auth: Mana Core Auth (JWT)

Commands

# 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-manadeck-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3321)
│   ├── app.module.ts         # Root module
│   ├── health.controller.ts  # Health check endpoint
│   ├── config/
│   │   └── configuration.ts  # Configuration & help messages
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   ├── manadeck/
│   │   ├── manadeck.module.ts
│   │   └── manadeck.service.ts # ManaDeck Backend API client
│   └── session/
│       ├── session.module.ts
│       └── session.service.ts  # User session & auth management
├── Dockerfile
└── package.json

Bot Commands

Command	Aliases	Description
!help	hilfe	Show help message
!login email pass	-	Login
!logout	-	Logout
!status	-	Bot status

Deck Management

Command	Aliases	Description
!decks	liste	List all decks
!deck [nr]	details	Show deck details
!neu Titel	new, create	Create new deck (10 Mana)
!loeschen [nr]	delete	Delete deck

Card Management

Command	Aliases	Description
!karten [nr]	cards	List cards in deck
!karte [deck-nr] [card-nr]	card	Show card details

AI Generation

Command	Options	Description
!generate Thema	generieren, gen	Generate deck with AI (30 Mana)
--count N	-	Number of cards (1-50)
--type TYPE	-	flashcard, quiz, text, mixed
--difficulty LEVEL	-	beginner, intermediate, advanced

Learning & Progress

Command	Aliases	Description
!lernen [nr]	study	Start study session
!faellig	due	Show due cards
!stats	statistik	Learning statistics
!mana	credits, guthaben	Show mana balance

Public Features

Command	Aliases	Description
!featured	empfohlen	Show featured decks
!leaderboard	rangliste	Show top 10 users

Example Usage

# Login
!login max@example.com mypassword

# Create a deck
!neu Spanisch Vokabeln | Grundwortschatz

# Generate deck with AI
!generate Deutsche Geschichte --count 20 --type flashcard

# List decks
!decks

# View cards
!karten 1

# Start studying
!lernen 1

# Check due cards
!faellig

# Check mana balance
!mana

Card Types

Type	Content Structure
text	{ text, formatting? }
flashcard	{ front, back, hint? }
quiz	{ question, options[], correctAnswer, explanation? }
mixed	`{ sections: Array<TextContent

Credit Costs (Mana)

Operation	Cost
Deck Creation	10 Mana
Card Creation	2 Mana
AI Card Generation	5 Mana
AI Deck Generation	30 Mana
Deck Export	3 Mana

Environment Variables

# Server
PORT=3321

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_ALLOWED_ROOMS=#manadeck:matrix.mana.how
MATRIX_STORAGE_PATH=./data/bot-storage.json

# ManaDeck Backend
MANADECK_BACKEND_URL=http://localhost:3009
MANADECK_API_PREFIX=/api

# Mana Core Auth
MANA_CORE_AUTH_URL=http://localhost:3001

Docker

# Build locally
docker build -f services/matrix-manadeck-bot/Dockerfile -t matrix-manadeck-bot services/matrix-manadeck-bot

# Run
docker run -p 3321:3321 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e MANADECK_BACKEND_URL=http://manadeck-backend:3009 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-manadeck-bot-data:/app/data \
  matrix-manadeck-bot

Health Check

curl http://localhost:3321/health

ManaDeck Backend API Endpoints Used

Endpoint	Method	Description
/public/health	GET	Health check
/public/featured-decks	GET	Featured decks
/public/leaderboard	GET	Leaderboard
/api/decks	GET	List user's decks
/api/decks	POST	Create deck
/api/decks/:id	GET	Get deck details
/api/decks/:id	DELETE	Delete deck
/api/decks/:id/cards	GET	Get cards in deck
/api/cards/:id	GET	Get card details
/api/decks/generate	POST	AI generate deck
/api/study-sessions	POST	Start study session
/api/progress/due	GET	Get due cards
/api/stats	GET	Get user stats
/api/credits/balance	GET	Get mana balance

Number-Based Reference System

The bot uses a number-based reference system for ease of use:

1. User runs !decks to get a list of decks
2. Bot stores the list internally for the user
3. User can reference decks by their list number
4. Numbers are valid until the user runs a new list command

Similarly for cards:

1. User runs !karten [deck-nr] to get cards
2. Cards can be referenced by !karte [deck-nr] [card-nr]

This allows simple commands like:

• !deck 3 - Show details for deck #3
• !karten 1 - Show cards in deck #1
• !karte 1 5 - Show card #5 in deck #1
• !lernen 2 - Start study session for deck #2