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

Matrix Presi Bot - Claude Code Guidelines

Overview

Matrix Presi Bot provides presentation management via Matrix chat. It integrates with the Presi backend for deck/slide management, theming, and sharing.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: Presi API (port 3008)
• 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-presi-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3325)
│   ├── 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
│   ├── presi/
│   │   ├── presi.module.ts
│   │   └── presi.service.ts  # Presi 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

Presentation Management

Command	Aliases	Description
!presis	decks, liste	List all presentations
!presi [nr]	deck, details	Show presentation with slides
!neu Titel	new, create	Create presentation
!loeschen [nr]	delete	Delete presentation
!umbenennen [nr] Titel	rename	Rename presentation

Slide Management

Command	Description
!folie [nr] titel Titel | Untertitel	Add title slide
!folie [nr] text Titel | Inhalt	Add content slide
!folie [nr] punkte Titel | P1, P2, P3	Add bullet slide
!folie [nr] bild Titel | URL	Add image slide
!folieloeschen [presi-nr] [folien-nr]	Delete slide

Themes

Command	Aliases	Description
!themes	designs	List available themes
!theme [presi-nr] [theme-nr]	design	Apply theme

Sharing

Command	Options	Description
!teilen [nr]	share	Share presentation
--tage N	-	Expire in N days
!links [nr]	shares	List share links

Slide Types

Type	Content
title	Title + optional subtitle
content	Title + body text
bullets	Title + bullet points
image	Title + image URL

Example Usage

# Login
!login max@example.com mypassword

# Create presentation
!neu Meine Praesentation | Eine tolle Praesentation

# List presentations
!presis

# Add title slide
!folie 1 titel Willkommen | Zur Praesentation

# Add content slide
!folie 1 text Einfuehrung | Hier ist der Inhalt

# Add bullet points
!folie 1 punkte Agenda | Punkt 1, Punkt 2, Punkt 3

# View presentation
!presi 1

# Apply theme
!themes
!theme 1 2

# Share presentation
!teilen 1 --tage 7

# View share links
!links 1

Environment Variables

# Server
PORT=3325

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

# Presi Backend
PRESI_BACKEND_URL=http://localhost:3008
PRESI_API_PREFIX=/api

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

Docker

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

# Run
docker run -p 3325:3325 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e PRESI_BACKEND_URL=http://presi-backend:3008 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-presi-bot-data:/app/data \
  matrix-presi-bot

Health Check

curl http://localhost:3325/health

Presi Backend API Endpoints Used

Endpoint	Method	Description
/health	GET	Health check
/api/decks	GET	List presentations
/api/decks	POST	Create presentation
/api/decks/:id	GET	Get presentation with slides
/api/decks/:id	PUT	Update presentation
/api/decks/:id	DELETE	Delete presentation
/api/decks/:id/slides	POST	Add slide
/api/slides/:id	DELETE	Delete slide
/api/themes	GET	List themes
/api/share/deck/:id	POST	Create share link
/api/share/deck/:id/links	GET	List share links

Number-Based Reference System

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

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

This allows simple commands like:

• !presi 2 - Show presentation #2
• !folie 1 titel Hallo - Add slide to presentation #1
• !theme 1 3 - Apply theme #3 to presentation #1