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

Matrix Questions Bot - Claude Code Guidelines

Overview

Matrix Questions Bot provides Q&A research management via Matrix chat. It integrates with the Questions backend for question management, web research via mana-search, answer tracking, and collection organization.

Tech Stack

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

Question Management

Command	Aliases	Description
!fragen	questions, liste	List all questions
!fragen offen	-	Filter by status
!frage [nr]	question, details	Show question details
!neu Frage?	new, ask	Create new question
!loeschen [nr]	delete	Delete question
!archivieren [nr]	archive	Archive question

Research

Command	Aliases	Description
!recherche [nr]	research	Start quick research
!recherche [nr] standard	-	Standard research (15 sources)
!recherche [nr] deep	-	Deep research (30 sources)
!ergebnis [nr]	result	Show research result
!quellen [nr]	sources	Show sources

Answers

Command	Aliases	Description
!antwort [nr]	answer	Show answer
!bewerten [nr] 1-5	rate	Rate answer
!akzeptieren [nr]	accept	Accept as solution

Collections

Command	Aliases	Description
!sammlungen	collections	List collections
!sammlung Name	collection	Create collection

Search

Command	Aliases	Description
!suche Begriff	search	Search questions

Research Depths

Depth	Sources	Content Extraction	Categories
quick	5	No	general
standard	15	Yes	general, news
deep	30	Yes	general, news, science, it

Question Status

Status	Emoji	Description
open	❓	New question
researching	🔍	Research in progress
answered	✅	Has answer
archived	📦	Archived

Priority Levels

Priority	Indicator
urgent	🔴
high	🟠
normal	(none)
low	(none)

Example Usage

# Login
!login max@example.com mypassword

# Create a new question
!neu Was ist Quantencomputing?

# List questions
!fragen

# Start research
!recherche 1 standard

# View sources
!quellen 1

# View answer
!antwort 1

# Rate the answer
!bewerten 1 5

# Accept as solution
!akzeptieren 1

# Search questions
!suche quantum

# Create collection
!sammlung Wissenschaft

Environment Variables

# Server
PORT=3324

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

# Questions Backend
QUESTIONS_BACKEND_URL=http://localhost:3011
QUESTIONS_API_PREFIX=/api/v1

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

Docker

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

# Run
docker run -p 3324:3324 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e QUESTIONS_BACKEND_URL=http://questions-backend:3011 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-questions-bot-data:/app/data \
  matrix-questions-bot

Health Check

curl http://localhost:3324/health

Questions Backend API Endpoints Used

Endpoint	Method	Description
/health	GET	Health check
/api/v1/questions	GET	List questions
/api/v1/questions	POST	Create question
/api/v1/questions/:id	GET	Get question
/api/v1/questions/:id	DELETE	Delete question
/api/v1/questions/:id/status	PUT	Update status
/api/v1/research/start	POST	Start research
/api/v1/research/question/:id	GET	Get research results
/api/v1/sources/question/:id	GET	Get sources
/api/v1/answers/question/:id	GET	Get answers
/api/v1/answers/:id/rate	POST	Rate answer
/api/v1/answers/:id/accept	POST	Accept answer
/api/v1/collections	GET	List collections
/api/v1/collections	POST	Create collection

Number-Based Reference System

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

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

This allows simple commands like:

• !frage 3 - Show details for question #3
• !recherche 1 deep - Start deep research for question #1
• !antwort 2 - Show answer for question #2